Skip to content

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

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

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

Conversation

@chenmingwei23

Copy link
Copy Markdown
Contributor

Draft. Replaces #36499, #36469 and #36016 (each stays untouched by this PR).

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. Both send dashboard_instance_changed when the page changed (not on a refusal, not when the page is kept). 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, the history file 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. Only the empty directory and its lock file stay, so a later adopt on the slug starts again at version 1 with no row of the removed import.
  • Where the directory walk cannot be pinned (native Windows has no O_NOFOLLOW), remove_adopted raises PinUnsupported; 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.
  • 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 and a message that says what to do. A card stored before this step has no dashboard key in its after-state and is not compared.
  • A failed dashboard step is named in the partial summary ("its dashboard").
  • Pins: MCP route table (354 rows) and the two boot chain-order pins, recomputed by running test_dashboard_server_composition_contract_reach.py on this base; facade manifests for the new helpers.
  • Docs: feature-map row (resolved against main's current text) and an RFC note.

Review findings carried over from #36499, #36469 and #36016:

Non-blocking points from the review of #36499:

  • Import onto a slug that already has a dashboard: not done. Undo of the adopted version removes the older retained versions of that slug too, as the remove_adopted docstring says. Recording the pre-adopt version or refusing the apply step would be a second behaviour change that needs its own design; it stays accepted.
  • No pinned walk: done, one logger.info line (no slug). A card line saying the page stays: not done, it is a UI text change outside this PR's scope.
  • The three 409 refusals: done, each logs one line (no slug).
  • adopt itself is not pinned, so a symlinked members/<slug> or dashboard lets the POST write through the link: pre-existing, the other dashboard routes on main do the same; not changed here.
  • Surviving mutations: added tests for the instance lock (test_remove_adopted_holds_the_instance_lock), the staged-preview and history removal, the not-shipped-origin refusal on both routes, an Undo without a recorded version, the origin check in _ships_builtin, and the one-path-segment guard.

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; run against main's code (before commit 2) it gives 27 failed and 36 passed across test_crewmate_import_dashboard.py and test_change_card_crewmate_import.py (the 4 that pass are guards, see below). Commit 2 holds the change and the pin updates.

Local runs (pytest -n0, one file at a time, under 2 minutes each):

  • test_crewmate_import_dashboard.py + test_change_card_crewmate_import.py: without the change 27 failed / 36 passed; with it all pass (test_crewmate_import_dashboard.py: 30 passed). The 4 tests that pass on main are guards for behaviour that must not change: a card stored before this step, a plain Bot delete and a create Undo leaving the dashboard alone, an id the receiver does not ship, and a page the catalog gives under another origin.
  • Touched area, each file alone: 52 files, 2311 tests, all passed (every test_change_card*, test_crewmate_*, test_dashboard_instance*, test_dashboard_templates*, template flow and manifest, the composition contract files including the pins, page offer, agent create template, b64 routes, client route contract, member goals cards, work-ledger facade). test_dashboard_server_composition_contract_reach.py: 17 passed on this base (354 MCP route rows, digest unchanged, chain pins +2 _deferred each).
  • test_facade_mirror_guards.py does not finish in 2 minutes as one file, so each of its 31 tests was run alone: all passed, including the manifest check and the tree scans that look at test patches.

New in test/test_crewmate_import_dashboard.py:

  • plan and route shape: 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_route_is_hooked_and_writes_no_memory_line (POST and DELETE)
  • adopt: test_the_card_step_sets_the_dashboard_on_the_new_bot (also instance_version), test_only_the_card_step_and_only_a_shipped_template_are_accepted, test_the_adopt_tells_open_dashboard_tabs_and_a_refusal_does_not
  • Undo: test_undo_removes_an_untouched_dashboard_before_the_bot_delete, test_undo_with_an_edited_dashboard_is_refused_and_the_page_stays, test_undo_completes_and_keeps_the_page_where_the_walk_cannot_be_pinned, test_the_undo_route_is_card_only_and_names_a_shipped_template, test_the_undo_route_tells_open_tabs_only_when_it_removed_the_page, test_a_template_that_is_not_shipped_is_refused_by_both_routes
  • removal: test_remove_adopted_refuses_another_template_or_version_and_removes_nothing, test_remove_adopted_never_follows_a_member_directory_swapped_for_a_link, test_remove_adopted_leaves_only_the_lock_and_a_later_adopt_starts_clean, test_remove_adopted_holds_the_instance_lock, test_remove_adopted_takes_one_path_segment_only
  • fingerprint: 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_undo_without_a_recorded_adopted_version_leaves_the_page_out_of_its_plan
  • old and neighbouring behaviour: test_an_old_import_card_without_a_dashboard_step_still_undoes, test_a_plain_bot_delete_and_a_create_undo_leave_the_dashboard, test_a_page_the_catalog_gives_under_another_origin_is_not_applied

Also: test_import_shares_the_create_state_read_and_partial_line asserts the "its dashboard" partial line. Tests that need a pinned directory walk are skipped where the platform lacks it.

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
- the adopt and the removal tell open Dashboard tabs (dashboard_instance_changed);
  a refusal or a kept page does not
- remove_adopted refuses another template or version, never follows a member
  directory swapped for a link, holds the instance lock, takes one path segment
  only, and leaves nothing but the lock file (history and preview go too)
- where the directory walk cannot be pinned (native Windows) the Undo still
  completes, the Bot is deleted and the page stays
- a template the catalog gives under another origin is neither applied nor
  removed; an Undo without a recorded adopted version leaves the page out
- 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; both
  tell open Dashboard tabs (dashboard_instance_changed) when the page changed
- 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);
  the record, versions, staged preview and history file all go, so a later
  adopt on the slug starts again at version 1
- 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 refusals and the kept case log one
  line each (no slug)
- 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 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 f57a6e236b0be930b1c26f4fb852bf3ba52a85d0 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 f57a6e236b0be930b1c26f4fb852bf3ba52a85d0 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

No design-level concerns: the dashboard step and its Undo follow the import card's existing card-only, owner-only step pattern, and Undo only removes the page at the version the step adopted.

Notes

  • A plain Bot delete leaves its dashboard instance behind. If a new import then lands on that same slug, its Undo also removes the dashboard history the deleted Bot left there. The description accepts this, but it is the one place this Undo deletes data that existed before the card ran. Recording the version that was there before the adopt would make Undo leave that history alone.

[DESIGN-REVIEWED] f57a6e2

Description read

[DESCRIPTION-READ] 82ce2e14fe4ceea36d7e4e4c4221de8d250468b8f300ee102eb0de06a89ad6a4

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 f57a6e236b0be930b1c26f4fb852bf3ba52a85d0 — 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

Every item has a named harm (#35701, the accepted rfc-crewmate-share.md import-card row "Dashboard | the builtin: template"), and no owner-side adopt or remove path exists today for it to duplicate.

What this change ships

Inventory (8 items) — 8 justified

Intent: when the receiver imports a shared Bot, it arrives with the built-in dashboard the sender chose, and the import card's Undo takes it back. ADDITION.

  1. Importing a Bot that names a built-in page this build ships sets that page on the new Bot from the same card — justified
  2. That page is no longer listed under "Not brought over"; a page the receiver does not ship still is — justified
  3. The card's Undo removes the adopted page (record, preview, history, retained versions), only at the version it adopted — justified
  4. Undo refuses with 409 and a "remove it from the Dashboard tab" message when the page changed after the import — justified
  5. On native Windows, Undo leaves the page and still finishes (no O_NOFOLLOW) — justified
  6. New owner-only, card-only routes POST/DELETE /api/members/{slug}/dashboard/template — justified
  7. Open Dashboard tabs reload when the import sets or removes the page — justified
  8. A failed dashboard step is named in the partial summary ("its dashboard") — justified

[FIRST-PRINCIPLES-REVIEWED] f57a6e2

Description read

[DESCRIPTION-READ] b35947b94ed294ada060c8771c662abab837677f9ab48b8a105f6ef641dc0d43

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 f57a6e236b0be930b1c26f4fb852bf3ba52a85d0 — this comment is updated in place on each push.

Review details

No findings.

Notes:

  • Once the Bot's page changes after an import (its own dashboard_apply or rollback counts), that import's Undo is refused for good, because the instance version never comes back down. It is the documented design, but it is a stricter rule than the rules part, where restoring the same text lets the Undo run.
  • remove_adopted catches only FileNotFoundError while it unlinks. Any other OSError there returns a 500 after instance.json and history.json are already gone.

[OPUS-REVIEWED] f57a6e2

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

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

@github-actions

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 f57a6e236b0be930b1c26f4fb852bf3ba52a85d0. 1 of 1 blocking finding(s) are security-class and were withheld from adjudication, so the blocking verdict stands.

This comment is updated in place on each push.

BLOCKING -- src/kiro_crew/dashboard_templates/instance.py:1277 -- Pin the versions directory before deleting the live dashboard

os.unlink(_RECORD_FILE, dir_fd=pinned)
Trigger: After an import, dashboard/versions is replaced by a symlink and the owner presses Undo. The snapshot checks only the dashboard record’s template/version, so _run_card_step reaches remove_adopted; opening versions with O_NOFOLLOW then raises OSError.
Outcome: The live record, preview and history are already deleted. The uncaught error returns 500, marks the card interrupted and withdraws its Undo plan, leaving the Bot undeleted and the operation non-retryable.
Anchor: residual/crash-data-loss-corruption
Fix: Open and pin versions before unlinking any dashboard files; translate a refused open into InstanceError while leaving the dashboard unchanged.

[BLOCK-MERGE] f57a6e2
[GPT-REVIEWED] f57a6e2

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

No adjudicable findings were listed (total=0). I'm flagging the one fenced finding (F1) instead of upholding it as written, but it keeps blocking either way.

F1: The defect is real. At instance.py:1277, remove_adopted deletes the dashboard record, preview and history first. Only then does it open versions with no-follow flags (instance.py:1284), and it catches only FileNotFoundError there. The handler at member_import_dashboard.py:101-108 catches only PinUnsupported and InstanceError, so a refused-link OSError comes back as a 500 after the dashboard is already partly removed. The only way to trigger it is for versions to be a symlink. The system's own writer always creates it as a real directory (os.mkdir at instance.py:1091), so it takes deliberate tampering. The files lost are the ones the owner's Undo was about to delete anyway, and no link is followed (dir_flags, pinned_fs_primitives.py:193). The real harm is a half-finished Undo that the gateway can't retry: the versions directory and the Bot are left behind (MEDIUM rung). The fix is cheap: open versions before the first unlink and convert the error to InstanceError.

[ADJUDICATION] f57a6e236b0be930b1c26f4fb852bf3ba52a85d0 total=0 uphold=0 downgrade=0
[GPT-ADJUDICATED] f57a6e236b0be930b1c26f4fb852bf3ba52a85d0

[ADJUDICATION-FENCED] f57a6e236b0be930b1c26f4fb852bf3ba52a85d0 fenced=1 flagged=1
FLAG F1 src/kiro_crew/dashboard_templates/instance.py:1277 -- Reaching this needs `versions` swapped for a symlink, which the system's own writer cannot produce (it calls os.mkdir at instance.py:1091), and the only loss is files the owner's Undo was already deleting, leaving a stuck, visible 500 rather than corrupted or exposed data.
[GPT-ADJUDICATED-FENCED] f57a6e236b0be930b1c26f4fb852bf3ba52a85d0

🏷️ Fenced finding(s) machine-flagged as likely edge case

The security fence keeps these findings blocking regardless of adjudication; the only clearance path is a human override. The annotate-only pass judged the condition combination each one requires extreme, and pre-drafted the override rationale below. A repository writer must independently verify a rationale before posting it — it is machine-authored, and a wrong override on a security-class finding ships exactly the class the fence exists to stop.

  • F1 src/kiro_crew/dashboard_templates/instance.py:1277 — Reaching this needs versions swapped for a symlink, which the system's own writer cannot produce (it calls os.mkdir at instance.py:1091), and the only loss is files the owner's Undo was already deleting, leaving a stuck, visible 500 rather than corrupted or exposed data.

    /ai-review override gpt f57a6e236b0be930b1c26f4fb852bf3ba52a85d0 <class>: Reaching this needs versions swapped for a symlink, which the system's own writer cannot produce (it calls os.mkdir at instance.py:1091), and the only loss is files the owner's Undo was already deleting, leaving a stuck, visible 500 rather than corrupted or exposed data.
    

Replace <class> with the class that records what you did. These findings are real, so for an accepted risk use owner-decision (link the decision comment in the reason) or deferred #<N> (a tracked follow-up issue); false-positive only if you verified the finding is wrong. Not not-applicable: that class files the override as a rule mismatch in the audit.

False positive or not applicable? A repository writer can comment:
/ai-review override gpt f57a6e236b0be930b1c26f4fb852bf3ba52a85d0 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 #36569: a new branch from current main that folds in the GPT 6.1 finding (pin the versions folder before the first delete), the flake-ratchet fix and the review's log assertions, 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