Repository navigation
feat(apps): pin crew-companion for adoption - #39004
Conversation
Crew Companion now lives in its own repository under KiroCrewCaptain, ported up to the current wheel copy with green CI on ubuntu, macOS and Windows. The row is the output of scripts/adoption_pin.py compute and is added to adoption-pins.json and the _SHIPPED_PINS table, so a host whose record is builtin-owned moves onto the app's own tree at its next restart and keeps data/, the grants and enabled. minAppSdkLevel is 7, the level of the displays, background and gutter its desktop windows declare. Every desktop shell a newer gateway can meet draws exactly one companion: a shell without the window host, or 0.13.0-rc.1's, keeps the built-in windows; 0.13.0-rc.2 and later stand the built-in down for a non-builtin origin and host the copy's windows. The wheel app.json version moves to the pinned 1.0.1 (D12), and the owning spec records the adoption. Part of #26967
UX Review (Opus 5.5) — ⏭️ skippedRevision |
|
Catalog row: kirodotdev/KiroCrewApps#91 switches crew-companion to |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Nothing blocks. The pin row is the move-out that AGENTS.md requires for the remaining built-ins under #26967. The version bump is what D12 asks for, and the spec edit is the update the same commit has to carry. What this change shipsInventory (5 items) — 5 justifiedIntent: at the next restart, hosts that run the built-in Crew Companion move to the app's own repository and keep all their data. This is an ADDITION carrying out a recorded decision (no new built-in apps, #26967).
[FIRST-PRINCIPLES-REVIEWED] cffc204 Description read[DESCRIPTION-READ] 59afa82866bbb5cede34c769df240375c4a845871f2dbb2cfc39940929bc6b18 That sha256 names the PR description this verdict read. Recompute it with |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks: the pin row and version bump follow the established adoption pattern, nothing is removed, and the description covers older shells meeting a newer gateway. Notes
[DESIGN-REVIEWED] cffc204 Description read[DESCRIPTION-READ] 4b0373f18285cd328c918bb76c3399752f1e5fb4757ddf9c0049cc1b5a5cdcf6 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 |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
I reviewed head cffc204. Recomputing the pin from the app repository at the pinned commit reproduced the committed row byte for byte, and its version 1.0.1 equals the bumped wheel manifest. The adopted manifest declares the same permissions as the wheel copy and no credential masks or desktop capabilities. Both copies use the same data file, the same appearance store root and the same 21 routes, so adoption keeps existing reminders, settings and avatars. I loaded the desktop window host rules from 0.13.0-rc.1, rc.2, rc.3, the 0.13.0 release branch and main against the adopted desktop block. rc.1 refuses the block whole, 0.12 has no host, and from rc.2 on the built-in stands down when the record is no longer built-in, so no desktop app draws two companions. The adoption and companion test files pass locally and CI is green, so nothing blocks.
Switch crew-companion from a builtin source to a git source in KiroCrewCaptain/kirocrew-app-crew-companion at the commit Kiro Crew's adoption pin table names for it (kirodotdev/KiroCrew#39004). Lands right after that pin PR.
Problem / Motivation
Goal: A host that has Crew Companion as a built-in moves onto the app's own repository at its next restart, keeping its reminders, settings, stats, avatars, grants and whether it was enabled, while every desktop app keeps showing exactly one companion.
Crew Companion now lives in its own repository (
KiroCrewCaptain/kirocrew-app-crew-companion), ported from the current wheel copy, with green CI on ubuntu, macOS and Windows. Its last seam, #37454 (built-in shell code steps aside for the window host), has merged. The wheel's adoption pin table does not name Crew Companion yet, so no host adopts it and every companion fix keeps having to land twice.Why it matters
Until a pin row exists, Crew Companion cannot leave core: every host keeps running the wheel copy and the built-in's main-process shell code, and the removal of the built-ins in #26967 cannot start for it.
Not a goal
scripts/adoption_pin.py, or the app's declared permissions.src/kiro_crew/apps/builtins/crew_companion/,website/src/apps/crew-companion/,website/electron/crew-companion/); only itsapp.jsonversion moves.What changed (motivation → approach → change)
Crew Companion gets an adoption pin row, so at its next restart a host whose Crew Companion is the built-in switches to the app's own repository at the pinned commit, keeping
data/(the reminder store with its settings and stats, imported avatars and their colours), the approved grants andenabled. The row is the output ofscripts/adoption_pin.py compute, copied intoadoption-pins.jsonand the_SHIPPED_PINStable:minAppSdkLevel2eb2e9846914displays,backgroundandgutterof itsdesktop.windows)computeaccepts--min-sdk-level 1for this tree: its seam scan reads nodesktop.windowskey. The window grammar is App Kit level 7 (app-kit-platform § 35, "Levelling": a gateway below 7 refusesdisplays,gutterandbackgroundat install), so the row carries 7, set by hand. The wheel built-inapp.jsonversion moves to 1.0.1, since a first-adoption pin must equal it (D12), and the wheel copy's owntest_manifest.py::test_identityfollows it. The repository declares the samepermissionsas the wheel copy (its own namespace,storage,network, thecrew-companion:fireevent, no cron), nocredentialMasks, nopermissions.desktopCapabilitiesand no shortcuts, so E9 holds nothing back. Itsdesktop.windowsare the four the built-in's shell code draws: the avatar overlay on every display, the background notification owner, the panel and the gallery. The owning spec, app-kit-platform § 35, records the adoption.The pinned tree carries every change its wheel copy has on
main5ca143070d. The repository was ported fromaf94fac51f(its #1); the later changes to the built-in's files are #34653 (the Scheduled theme in the window theme helper; nothing to carry, since a hosted window loads the dashboard's own document, whose theme provider resolves Scheduled), and #37430 and #37454 (shell-side stand-down rules; nothing to carry, the repository has no main-process code). Its #2 records them inPORTING.md, #4 pins the monotonic clock in a store test that failed on a runner booted less than a minute earlier, and #3 released 1.0.1 as2eb2e9846914.App repo: KiroCrewCaptain/kirocrew-app-crew-companion@2eb2e98
Wheel-copy base: crew-companion@5ca143070dcc3fc9e03db9fc1099da4ecddf8ceb
Desktop apps without #37454
A pin row ships in the wheel, so it reaches hosts in the next release cut from
main, which also carries #37454. The desktop app's own bundled gateway is never newer than the app (its updater replaces the whole bundle), but a gateway installed separately, run as a service or reached over an SSH tunnel follows its own updates, so a newer gateway can meet a desktop app without #37454: 0.12 and earlier, the 0.13.0 release candidates, and a 0.13.0 cut fromrelease/0.13.0, which does not carry #37454. I ran the built-in shell code and the window host rules of each of those releases against the real/api/appsrows the smoke gateway below served (the built-in record before the upgrade, the adopted record after it):displays,backgroundandgutter, and drops the declaration whole)release/0.13.0tipbuiltinorigin(#37430)main(with #37454)originand on thedesktopblockNo desktop app draws both, and none draws anything while the app is off. On the first two rows the built-in windows load from the pages the wheel still ships at
/app-windows/crew-companion/and call the same routes, which the adopted copy serves with the same shapes over the same data (the smoke loads those pages and drives those routes after adoption). So, unlike the general case § 35 warns about, this pin does not need a later desktop release, and needs no shell capability gate. The wheel's window pages are what the older desktop apps draw, so deleting the wheel copy has to wait for them; § 35 now says so.Backwards compatibility
Compatible: one row is added and one version moves up. A host whose record is builtin-owned adopts at the next restart and keeps
data/, the grants andenabled; a host that cannot adopt (an SDK level below 7, a pending config review, a file besideapp.jsonthe tree does not ship) keeps the wheel copy unchanged. Every desktop app shows one companion, from the built-in windows or from the host, as the table above shows.Removes nothing: the wheel copy, its window pages at
/app-windows/crew-companion/, its/crew-companionroute, its shell code and every existing pin row stay.Tests
test/test_builtin_adoption_pins.py::test_the_shipped_pin_file_validates_and_pins_exactly_the_shipped_tabletakes the new row and fails with the pin file ofmain;test_every_shipped_pin_matches_its_wheel_built_in_versionand the wheel copy'stests/test_manifest.py::test_identityhold the version bump.Proof: PROVEN src/kiro_crew/apps/builtins/crew_companion/tests/test_manifest.py::test_identity, test/test_builtin_adoption_pins.py::test_the_shipped_pin_file_validates_and_pins_exactly_the_shipped_table (head cffc204)
Determinism: no test logic changes, only the pinned data table and one expected version. With this commit on
main62df088708(rebased since onto54b60f24a9, which brings nothing underapps/, the window host or the App SDK), run serially with an isolated--basetemp: everytest/file that namesadoption_pin,adoption-pins,crew_companion,crew-companionor Crew Companion (test_builtin_adoption_*.py,test_adopted_wheel_copy_check.py,test_builtin_permission_parity.py,test_appearance_packs_*.py,test_apps_doc_catalogue.pyamong them),test_legacy_state_moves.py,test/integration/test_builtin_adoption_boot.py,test_flake_pattern_ratchet.pyand the wheel copy's owntests/: 1751 passed, 4 skipped. Black, isort, flake8, mypy, subprocess-encoding, comment-history, brand-name, line-cap and harness-parity gates andscripts/docs-lint.shpass..github/scripts/adopted_wheel_copy_check.pypasses on this body, and fails with the port baseaf94fac51f(namingdashboardTheme.ts).Manual verification
scripts/adoption_pin.py computeat2eb2e9846914with--min-sdk-level 7prints the committed row byte for byte.scripts/adoption_pin.py verifyover the network: all nineteen rowsok, this one included. The pinned commit is the head of the repository'smain, with every check run green on ubuntu, macOS and Windows.Upgrade smoke on isolated loopback gateways (throwaway
HOMEandKIROCREW_HOME, the crew-companion row asKIROCREW_HARNESS_ADOPTION_PINS, a real GitHub fetch, Kiro Crew's fake ACP backend). Each home was first booted onmain62df088708, before this change; then this branch booted twice (STAGE, APPLY), once with Crew Companion enabled at the upgrade and once with it disabled:/crew-companionand its window pages/app-windows/crew-companion/{pet,panel,gallery}.htmlloadstaged); the record stays the built-inorigin: registry,sourceCommit2eb2e9846914, version 1.0.1,enabledkeptenabled: falsekept)data/byte-equal to the state boot 2 started from (the store, the colours, the imported pack), approved grants equal, no app crons before or after/api/appsrow:adoption.stateadopted, legacy nav/crew-companionwith theGhostglyph, the fourdesktop.windows/apps/crew-companion/ui/dist/*.mjs); the built-in's window pages still load/pending; remove; an unauthenticated write is refused (403)adopted,installed.jsonbyte-equal, nothing fetcheddata/; after a restart no built-in comes backdata/equal to before the uninstall plus the gateway's dependency lock; a restart shows one record/popout/desktop/crew-companion/<window>) rendered in headless Chromium with a stub shell bridge: each callsready()with no page error or failed request; the avatar reports its hit region at the saved position, the panel lists both reminders and "Breaks every ~45 min", the gallery shows the imported avatar activeNo ERROR or traceback in any gateway's stderr. Agent tools and MCP: none declared on either copy (the enable registration lists no agents, skills, crons or MCP servers). In the enabled run the app advances its own activity counters (time kept company, streak, active hours) on every tick while it runs, so
data/is compared with the state the APPLY boot started from, and the route answers exclude the smoke's own reminder writes. Update and reinstall ran against the published catalog with only crew-companion's row switched togitat this commit (the KiroCrewApps PR below), served in place of the catalog fetch; with today'sbuiltinrow an adopted record has no install source until that PR lands, as for every earlier pin.Desktop:
node --test test/app-window-*.test.js crew-companion/test/*.test.jsinwebsite/electron: 282 pass, 0 fail. Not exercised headless: a real Electron window host (one avatar spanning several displays and the drag between them, click-through over the hit regions, focus, the background window reopening after a crash) and the display hand-off from the built-in's saved display; the shell's unit tests cover those with Electron stubbed. On the 0.12 and 0.13.0-rc.1 rows of the table above, the built-in windows over the adopted routes were exercised through those routes and pages, not in a real desktop app of those versions.Screenshots / video
N/A: the diff changes no
website/file and no rendered surface; the windows a user sees are the pinned repository's, rendered headless in the smoke table above.Related Issues
Part of #26967
Unblocked by #37454 and #37430. Catalog row: the kirodotdev/KiroCrewApps PR linked in a comment below switches crew-companion to
gitat the same commit. It is not auto-merged: it lands right after this PR.Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement
Contributed under the project's Apache-2.0 license.