Skip to content

feat(apps): pin crew-companion for adoption - #39004

Merged
KiroCrewCaptain merged 1 commit into
mainfrom
feat/pin-crew-companion
Nov 18, 2026
Merged

KiroCrewCaptain merged 1 commit into
mainfrom
feat/pin-crew-companion

Conversation

@bolichen97

Copy link
Copy Markdown
Contributor

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

  • Changing the adoption machinery, the window host, the D12 equality rule, scripts/adoption_pin.py, or the app's declared permissions.
  • Deleting the wheel copy (src/kiro_crew/apps/builtins/crew_companion/, website/src/apps/crew-companion/, website/electron/crew-companion/); only its app.json version moves.
  • Removing the core references that name the built-in (they go with the wheel copy).
  • Changing any other pin row, or the catalog (that is the KiroCrewApps PR below).

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 and enabled. The row is the output of scripts/adoption_pin.py compute, copied into adoption-pins.json and the _SHIPPED_PINS table:

App Version Pinned commit minAppSdkLevel
crew-companion 1.0.0 to 1.0.1 2eb2e9846914 7 (the displays, background and gutter of its desktop.windows)

compute accepts --min-sdk-level 1 for this tree: its seam scan reads no desktop.windows key. The window grammar is App Kit level 7 (app-kit-platform § 35, "Levelling": a gateway below 7 refuses displays, gutter and background at install), so the row carries 7, set by hand. The wheel built-in app.json version moves to 1.0.1, since a first-adoption pin must equal it (D12), and the wheel copy's own test_manifest.py::test_identity follows it. The repository declares the same permissions as the wheel copy (its own namespace, storage, network, the crew-companion:fire event, no cron), no credentialMasks, no permissions.desktopCapabilities and no shortcuts, so E9 holds nothing back. Its desktop.windows are 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 main 5ca143070d. The repository was ported from af94fac51f (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 in PORTING.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 as 2eb2e9846914.

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 from release/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/apps rows the smoke gateway below served (the built-in record before the upgrade, the adopted record after it):

Desktop app Built-in record, on Adopted record, on Adopted record, off
0.12.2 (no window host) built-in windows built-in windows nothing
0.13.0-rc.1 (its host refuses displays, background and gutter, and drops the declaration whole) built-in windows built-in windows; the host hosts nothing nothing
0.13.0-rc.2, rc.3 and the release/0.13.0 tip built-in windows the host's four windows; the built-in closes on the non-builtin origin (#37430) nothing
main (with #37454) built-in windows the host's four windows; the built-in closes on origin and on the desktop block nothing

No 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 and enabled; a host that cannot adopt (an SDK level below 7, a pending config review, a file beside app.json the 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-companion route, 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_table takes the new row and fails with the pin file of main; test_every_shipped_pin_matches_its_wheel_built_in_version and the wheel copy's tests/test_manifest.py::test_identity hold 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 main 62df088708 (rebased since onto 54b60f24a9, which brings nothing under apps/, the window host or the App SDK), run serially with an isolated --basetemp: every test/ file that names adoption_pin, adoption-pins, crew_companion, crew-companion or 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.py among them), test_legacy_state_moves.py, test/integration/test_builtin_adoption_boot.py, test_flake_pattern_ratchet.py and the wheel copy's own tests/: 1751 passed, 4 skipped. Black, isort, flake8, mypy, subprocess-encoding, comment-history, brand-name, line-cap and harness-parity gates and scripts/docs-lint.sh pass. .github/scripts/adopted_wheel_copy_check.py passes on this body, and fails with the port base af94fac51f (naming dashboardTheme.ts).

Manual verification

scripts/adoption_pin.py compute at 2eb2e9846914 with --min-sdk-level 7 prints the committed row byte for byte. scripts/adoption_pin.py verify over the network: all nineteen rows ok, this one included. The pinned commit is the head of the repository's main, with every check run green on ubuntu, macOS and Windows.

Upgrade smoke on isolated loopback gateways (throwaway HOME and KIROCREW_HOME, the crew-companion row as KIROCREW_HARNESS_ADOPTION_PINS, a real GitHub fetch, Kiro Crew's fake ACP backend). Each home was first booted on main 62df088708, before this change; then this branch booted twice (STAGE, APPLY), once with Crew Companion enabled at the upgrade and once with it disabled:

Check Enabled Disabled
Seed on the built-in: enabled, two reminders (one repeating), settings (breaks every 45 min, task alerts off, a saved avatar position, a colour preset), an imported avatar recoloured and set active, a breathing session, a queued gallery command PASS PASS (then disabled)
The built-in page /crew-companion and its window pages /app-windows/crew-companion/{pet,panel,gallery}.html load PASS PASS
Boot 1 stages the pinned commit (git fetch, ledger staged); the record stays the built-in PASS PASS
Boot 2 adopts: origin: registry, sourceCommit 2eb2e9846914, version 1.0.1, enabled kept PASS PASS (enabled: false kept)
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 PASS PASS (also byte-equal to the seed)
/api/apps row: adoption.state adopted, legacy nav /crew-companion with the Ghost glyph, the four desktop.windows PASS PASS
The routes answer the seeded reminders, settings, stats, avatars and colours PASS PASS (after enable)
The page and the four window bundles load from the adopted tree (/apps/crew-companion/ui/dist/*.mjs); the built-in's window pages still load PASS PASS
An owner write; a reminder due now fires into /pending; remove; an unauthenticated write is refused (403) PASS PASS
Boot 3 is a no-op: ledger adopted, installed.json byte-equal, nothing fetched PASS PASS
Disable (the routes answer 404), enable (back, same state) PASS PASS
Update from the store at the same commit; the page loads; reminders, settings and avatars kept not run PASS
Uninstall keeps only data/; after a restart no built-in comes back PASS not run
Reinstall from the store (trust prompt grant, install at the catalog commit, enable): data/ equal to before the uninstall plus the gateway's dependency lock; a restart shows one record PASS not run
The four hosted window documents (/popout/desktop/crew-companion/<window>) rendered in headless Chromium with a stub shell bridge: each calls ready() 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 active not run PASS

No 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 to git at this commit (the KiroCrewApps PR below), served in place of the catalog fetch; with today's builtin row 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.js in website/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 git at the same commit. It is not auto-merged: it lands right after this PR.

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

Contributed under the project's Apache-2.0 license.

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
@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners November 18, 2026 05:22
@bolichen97
bolichen97 enabled auto-merge (squash) November 18, 2026 05:22
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 18, 2026
@github-actions

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

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

@bolichen97

Copy link
Copy Markdown
Contributor Author

Catalog row: kirodotdev/KiroCrewApps#91 switches crew-companion to git at 2eb2e98469149ea740d7f82b6df701dbf872c9a3, the commit this PR pins. It is not auto-merged and lands right after this PR.

@github-actions

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of cffc20478dc308288e6d0fe8e9f3c15be17d0818 — 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 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 ships

Inventory (5 items) — 5 justified

Intent: 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).

  1. At restart, a host with the built-in Crew Companion swaps to the pinned external tree and keeps data/, its grants and enabled — justified
  2. The wheel built-in's manifest version moves from 1.0.0 to 1.0.1, matching the pin (D12) — justified
  3. Adoption requires App SDK level 7, and hosts below that keep the wheel copy — justified
  4. The adopted app keeps the /crew-companion rail route and the Ghost icon — justified
  5. Spec § 35 records the adoption and keeps the wheel window pages until older shells are no longer supported — justified

[FIRST-PRINCIPLES-REVIEWED] cffc204

Description read

[DESCRIPTION-READ] 59afa82866bbb5cede34c769df240375c4a845871f2dbb2cfc39940929bc6b18

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

Review details

No findings.

[OPUS-REVIEWED] cffc204

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

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

@github-actions

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

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

  • minAppSdkLevel 7 is set by hand because scripts/adoption_pin.py doesn't scan desktop.windows. The next window-bearing pin will hit the same gap, so teaching compute that grammar is a worthwhile follow-up.
  • The wheel's /app-windows/crew-companion/ pages are now load-bearing for 0.12 and 0.13.0-rc.1 shells. Deleting the wheel copy under Move every built-in app out to KiroCrewApps and forbid built-in apps #26967 needs a pinning test or a tracked issue, not only the spec sentence.

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

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] cffc204

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

@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 Nov 18, 2026

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

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.

@KiroCrewCaptain
KiroCrewCaptain merged commit d817489 into main Nov 18, 2026
97 checks passed
@KiroCrewCaptain
KiroCrewCaptain deleted the feat/pin-crew-companion branch November 18, 2026 06:53
KiroCrewCaptain pushed a commit to kirodotdev/KiroCrewApps that referenced this pull request Nov 18, 2026
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.
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 18, 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.

2 participants