Skip to content

feat(desktop): hand the companion's windows to its installed copy - #37430

Merged
bolichen97 merged 1 commit into
mainfrom
feat/w7-crew-companion
Nov 15, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
feat/w7-crew-companion

Conversation

@bolichen97

@bolichen97 bolichen97 commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Once Crew Companion's own repository copy is adopted, a desktop user sees one avatar and gets each reminder once, on the display they left the avatar on.

The built-in's desktop shell code (website/electron/crew-companion/index.js) opens its avatar overlays and its hidden notification owner whenever the gateway's /api/apps row named crew-companion is enabled. It never reads who owns the row. After adoption (#26967) the row is a registry record of the same name, still enabled, and the desktop window host (#36338) opens the copy's own declared windows for it. Both would run: two avatars, two notification owners, every reminder and session alert twice.

The window host also remembers the avatar's display under <app>/<window id> in app-window-displays.json, while the built-in remembers it in its own crew-companion-pet-position.json. With nothing in the host's file, the copy's avatar opens on the display under the cursor.

Why it matters

Crew Companion cannot be pinned for adoption while this stands: every existing desktop user who has it enabled would get a duplicated companion on their first start after adoption. The display change hits every multi-display user once.

Not a goal

  • Adopting Crew Companion: its repository, pin row and catalog row are separate changes.
  • Deleting website/electron/crew-companion/: the built-in keeps its windows until its copy is adopted, and the directory leaves with the wheel copy.
  • Any change to the generic window host: it still names no app.

What changed (motivation → approach → change)

Goal: the built-in shell stands down exactly when its copy takes over, and hands the copy its display. Approach: keep both in the built-in's own shell directory (which leaves with it) rather than teach the generic host about one app.

  • crew-companion/index.js: probeEnabled answers a new state, released, for a row whose origin is a string other than builtin; the reconcile closes the avatar, panel and gallery for it exactly as for disabled, whatever the row's enabled says. A row without origin (a gateway older than the field) is the built-in's, as before. One log line says why the windows closed.
  • crew-companion/displayHandOff.js (new): seedHostDisplayMemory(userDataDir, hostFile) copies the built-in's remembered displayId into the host's memory under crew-companion/pet (the avatar window the app's repository declares) and records the value copied in crew-companion-display-handoff.json. At a later start it copies again only while the host's entry still holds that recorded value: before adoption the built-in avatar is the one the user moves, so a newer display reaches the host; once the host has written a display of its own (the adopted avatar was moved), it is never overwritten. Never over an unreadable host file; files it writes are 0600. initCrewCompanion runs it, synchronously, before main.js goes on to createAppWindowHost, because the host reads its file once, on first use. main.js only passes the userData directory and the host's file path into the existing initCrewCompanion call, so it imports and calls nothing new of the built-in.
  • package.json: the new module joins the packaged file list.
  • Spec: app-kit-platform.md §35 "What still runs in the shell".

Backwards compatibility

Compatible: for every row the gateway marks origin: "builtin", and for a row without origin, the companion behaves as on main. A seeded display entry is read only for an installed app of this name declaring a spanning window pet.

Removes nothing: the built-in keeps every window and IPC handler; only a row that is not its own closes them.

Tests

  • website/electron/crew-companion/test/adoptedStandDown.test.js (new): an adopted row closes the avatar, panel and gallery and an enabled adopted row never reopens them; an adopted row opens nothing on a fresh start; a row without origin opens as before; probeEnabled answers released for a non-builtin row whether enabled or not; the built-in's display seeds the host's memory beside another app's entry; a host file the hand-off creates is owner-only; a display the host chose itself is never overwritten; a move of the built-in avatar after the first start reaches the host on the next; after adoption the host's own move survives every later start; no built-in display, a non-numeric one, or an unreadable host file writes nothing; initCrewCompanion writes the host's file before it returns, and main.js names nothing of the hand-off.
  • With index.js reverted to main (the hand-off module kept), the four stand-down cases fail; with the first round's copy-once hand-off, the move-after-the-first-start case fails.
  • Full Electron suite (npm test in website/electron): 3861 pass, 0 fail.
  • This diff changes no Python.
  • Determinism: no clocks, no sleeps beyond setImmediate settling, temporary directories per test.

Proof: not provable -- frontend test (prove.py runs Python only)

Manual verification

The shell was not run against a live desktop here; the reconcile and the hand-off are driven through their exported functions with Electron stubbed, as the existing companion tests do.

Related Issues

Part of #26967

A generic stand-aside rule for every built-in desktop shell is being built separately (branch feat/app-seam-desktop-host-serve); this PR keeps the companion's own check in its own directory and adds no shared helper.

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; see the Licensing section of CONTRIBUTING.md.

@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners November 15, 2026 00:39
@bolichen97
bolichen97 enabled auto-merge (squash) November 15, 2026 00:39
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 15, 2026
@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

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

UX-Verdict: PASS

Nothing to check. The diff adds and changes no visible control, label or string. It only closes the built-in companion's windows once its installed copy takes over, and passes the remembered display to that copy.

[UX-REVIEWED] e65f46a

Description read

[DESCRIPTION-READ] 158544b510852fe363eff022b96eaec00547564abf0822f25ddb2d2467d41940

That sha256 names everything this verdict read: the PR description, plus the 3 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 Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

No design-level concerns: the built-in shuts its own windows when the row's origin is no longer builtin, and the display hand-off stays in the built-in's directory, so the generic window host still names no app.

Notes

  • After adoption, seedHostDisplayMemory still runs at every start until the directory is deleted. Once crew-companion/pet is in the host's file and differs from the recorded value, it can return early without reading anything else. That cleanup can go in when the directory is removed.

[DESIGN-REVIEWED] e65f46a

Description read

[DESCRIPTION-READ] e65f69fb9f06ef70c2a633d153cdb63a9d819858ebaf17d672f346e0cdf9d947

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

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of e65f46a22478abee903e1213f6605ec4c5c22629 — 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. Each item removes a named duplication or misplacement harm that is reachable at adoption. One shell with the same root cause is left unfixed, and the description already defers it.

Notes

  • Item 1 — symptom-level: the cause is that a built-in desktop shell never reads origin. mochi/index.js:616 has the same enabled ? "enabled" : "disabled" check and is left unfixed (grep enabled ? "enabled" outside tests: 2 hits, 1 fixed). The description defers this ("A generic stand-aside rule … is being built separately"). Subtraction: when the generic rule lands, delete the companion's own released branch instead of keeping two spellings.
  • Item 2 — oversized: crew-companion-display-handoff.json is a new persisted record. Its only job is to let a move made before adoption reach the host, and it stays on disk after the built-in is gone. Subtraction: delete the record file and seed only when crew-companion/pet is absent from the host file.

What this change ships

Inventory (4 items) — 2 justified

Intent: after Crew Companion's repository copy is adopted, a desktop user sees one avatar, gets each reminder once, and finds the avatar on the display they left it on. This is an ADDITION (adoption groundwork).

  1. The built-in avatar, panel and gallery close once the gateway row's origin is not builtin — symptom-level: Mochi's shell keeps the same unread-origin check
  2. At startup the built-in avatar's display is copied into the host's display memory under crew-companion/pet — oversized: a persisted hand-off record file
  3. A new log line says the built-in overlays closed because the app's own copy is installed — justified
  4. main.js passes the userData directory and the display-memory path into initCrewCompanion — justified

[FIRST-PRINCIPLES-REVIEWED] e65f46a

Description read

[DESCRIPTION-READ] f6d1b687b84e208ab028fde48a3188804f2a494d9d2ef86981a47fdd2398b7cd

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] e65f46a

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

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

@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] e65f46a

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

@KiroCrewCaptain

KiroCrewCaptain commented Nov 15, 2026 •

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: Approve

Why: the decider estimates a 12% chance that this change introduces a defect, within the 12% limit for approving on its own, and every check passes.

The built-in companion's reconcile now returns released for any /api/apps row whose origin is a string other than builtin. Records carry that field (builtin|registry|local|external, migrated for old records). released runs the same close path as disabled: closePetWindow destroys every avatar overlay and the hidden brain window that owns notifications, so there are no duplicate avatars or reminders. Rows without origin behave as on main. The display hand-off writes {"crew-companion/pet": number}, which matches the host's display-memory format and key (app-window-span.js createDisplayMemory/spanKey). It runs synchronously in initCrewCompanion before createAppWindowHost, and the host loads its file once, on first use. It only copies again while the host's entry still equals the value it last copied, so the host's own drag-written choice is never overwritten. It never touches an unreadable host file and keeps other apps' entries. The new test file is picked up by the npm test glob, the file is in the packaged list and the spec is updated. Electron shell tests passed; other jobs were still running at review time. Nothing blocking found.

An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit e65f46a224 · 387 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@bolichen97
bolichen97 force-pushed the feat/w7-crew-companion branch from 1907d25 to fb84713 Compare November 15, 2026 01:13
@bolichen97

bolichen97 commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: display hand-off record

  • span=b9ec6840815a pre-adoption seeding froze an obsolete display

fixed in fb84713: the hand-off records the value it copied (crew-companion-display-handoff.json) and copies again at each start while the host's crew-companion/pet entry still holds that value, so a move of the built-in avatar before adoption reaches the host on the next start.
Once the host's entry differs from the record the host wrote a display of its own and it is never overwritten; after adoption the built-in's file no longer changes, so a copy can only repeat the host's value.
Pinned by a move of the built-in avatar after the first start reaches the host on the next (red on 1907d25) and after adoption the host's own move survives every later start.

@bolichen97

bolichen97 commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: display hand-off record

  • span=4cecdd578b57 pre-adoption seeding froze an obsolete display

fixed in fb84713: the hand-off records the value it copied (crew-companion-display-handoff.json) and copies again at each start while the host's crew-companion/pet entry still holds that value, so a move of the built-in avatar before adoption reaches the host on the next start.
Once the host's entry differs from the record the host wrote a display of its own and it is never overwritten; after adoption the built-in's file no longer changes, so a copy can only repeat the host's value.
Pinned by a move of the built-in avatar after the first start reaches the host on the next (red on 1907d25) and after adoption the host's own move survives every later start.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Nov 15, 2026
Once Crew Companion's own repository copy is adopted, the desktop window
host draws its avatar, notification owner, panel and gallery from that
copy's manifest. The built-in's shell code keyed only on the app name and
its enabled flag, so it would keep drawing a second avatar and run a
second notification owner, firing every reminder twice.

Its reconcile now reads a row whose origin is not builtin as released and
closes its windows; a row without origin is the built-in's, as before.
Before the window host starts, main.js copies the display the built-in
avatar last lived on into the host's display memory for the copy's avatar
window, only while the host has none, so a multi-display user finds the
avatar where it was.

Part of #26967
@bolichen97
bolichen97 force-pushed the feat/w7-crew-companion branch from fb84713 to e65f46a Compare November 15, 2026 01:54
@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: display hand-off record

  • span=07e410fd564c core main.js imported and called the built-in's hand-off

fixed in e65f46a: initCrewCompanion now runs seedHostDisplayMemory itself, synchronously, before main.js reaches createAppWindowHost; main.js only passes userDataDir and displayMemoryPath into the existing initCrewCompanion call, which leaves with the built-in's require row.
Class swept: every crew-companion name main.js references (initCrewCompanion, shutdownCrewCompanion, suspendCrewCompanion, resumeCrewCompanion) predates this PR; the seedHostDisplayMemory export from index.js is gone.
Pinned by initCrewCompanion runs the hand-off itself, so main.js calls nothing of it in adoptedStandDown.test.js; Electron suite 3861 pass, 0 fail.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Nov 15, 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.

Approving. On this head the review checked four things:

  • The stand-down reads origin from the /api/apps row. Built-in rows stay "builtin" because the app.json has no ui.entry, and a row with no origin keeps main's behaviour.
  • The hand-off key and value match the host's spanKey shape and the display id that petOverlay saves. The seeding runs before createAppWindowHost.
  • Every failure path writes nothing, and the new file is in the packaged files list.
  • Reverting each new branch turns its test red.

Done well: one record tells a display the built-in copied apart from one the host chose. A move made before adoption still reaches the host, and a move made after adoption is never overwritten.

Optional:

  • Add a source-order test that pins main.js passing userDataDir and displayMemoryPath to initCrewCompanion before createAppWindowHost(. Today the suite stays green if that hunk is dropped.
  • In one hand-off test, read the seeded file back through the host's own createDisplayMemory(...).get(spanKey("crew-companion", "pet")), not through HOST_KEY.
  • #37454 adds a second stand-down check at the same probeEnabled line. Whichever PR lands second could keep one predicate instead of both, and say which one in its body.

@bolichen97
bolichen97 merged commit fda5c79 into main Nov 15, 2026
155 of 157 checks passed
@bolichen97
bolichen97 deleted the feat/w7-crew-companion branch November 15, 2026 05:16
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 15, 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