Skip to content

feat(app-kit): let desktop windows use declared shell capabilities - #36349

Merged
bolichen97 merged 1 commit into
mainfrom
feat/w5-desktop-mochi
Nov 14, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
feat/w5-desktop-mochi

Conversation

@bolichen97

@bolichen97 bolichen97 commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A desktop app's own windows can capture the screen, reveal or open a local file, and switch among the operator's gateways, each only when the app declares it and the owner approved it, so Mochi can move onto the generic desktop window host.

The window host from #32654 lets an app's page shape only its own windows. Mochi's snip, its "show in Finder" and image viewer links, and its instance switcher (SSH crews included) reach the shell through Mochi's own main-process code, which no external app may ship. Owner ruling on #26967 (comment 6841699202, 2026-11-13, item 3) approves these as generic, manifest-declared, install-disclosed shell seams.

Why it matters

Mochi cannot leave core (#26967) while the features its users rely on exist only as Mochi-specific shell code. Without a declared seam, an external Mochi would lose screen snips, file links and its remote-crew switcher.

Not a goal

  • Moving Mochi's windows (pet overlay, panel, settings, avatar, snip) onto the host: that also needs the cross-display hand-off and background window kind from feat(app-kit): span a desktop overlay across displays, add background windows #36338 and user-rebindable shortcuts.
  • Removing website/electron/mochi/ or creating Mochi's app repository.
  • Changing what Mochi's shell code does today.
  • Any capability beyond the three Mochi already uses.

What changed (motivation → approach → change)

Goal: Mochi's three shell features as app-agnostic, declared seams of the window host.

Approach: one grant family, modeled on permissions.reachableByUserSessions (#34837), so disclosure, staging and approval reuse the existing machinery; the shell stays the enforcement point and serves only declared ∩ approved.

  • Gateway. permissions.desktopCapabilities (screenCapture, localFiles, gatewayChoice; unknown entries dropped) in apps/desktop_capabilities.py. Explicit-only staged grant family: an install approves it, an update that adds one waits, a set stored before the key approves none, a built-in's packaged declaration is approved. App rows carry desktopCapabilitiesGrant. Disclosed in the catalog projection and the CLI install summary. The key shares App Kit seam level 7 with the other seams of this release, and scripts/adoption_pin.py maps it there.
  • Shell. Bridge level 2, shared with feat(app-kit): span a desktop overlay across displays, add background windows #36338's calls. A screenCapture window is registered with capture-trust.js. revealFile and openImage run the new app-local-files.js. listGateways and chooseGateway run the new app-window-gateways.js: it rides only tunnels core reports connected, asks core's connected-only connect for the token, loads a crew only where the same app is enabled, declares every window this computer opens and has gatewayChoice approved (so its windows can always come back), keeps the windows on a non-answer, and shows the page no host name, port or credential. A reused crew is re-read from core's registry on every tick and before any window loads or reloads from it, and re-resolved when the app's windows here change; a crew no longer connected on its port is dropped, so a port another crew took over is never sent its token. A window a crew serves gets only the capabilities the app holds on both gateways (approved here and in that crew's desktopCapabilitiesGrant), so another gateway's bundle never gets one its own owner did not approve. The choice is kept per app in the shell store. A window whose served set changes is closed. The two new modules are in build.files (website/electron/package.json).
  • Dashboard. The trust prompt (TrustAppModal.tsx) and the app page (AppDetailGrantBoxes.tsx, AppDetailPage.tsx, row types, the enableApp consent type in api/client/apps.ts) show each capability from desktopCapabilityLine in components/appstore/desktopCapabilities.ts; trustGrants.ts carries the declaration to every place that opens the trust prompt; "Approve new permissions" approves a held-back one. The page's staged-grant reading moves to appDetailPageStagedGrants.ts, keeping AppDetailPage.tsx under the line cap. New strings in all 12 website/src/i18n/locales/*.json (en.manual.json for English, en-XA.json regenerated). desktopWindow/desktopWindowTarget.ts types the level 2 calls.
  • Mochi. Its manifest declares the three it uses (wheel copy first, E9). Its reveal-file and open-image handlers call app-local-files.js with identical rules.

Specs: app-kit-platform §35, mochi.md, manifest and API references, electron README; the App detail row of docs/feature-map/README.md lists appDetailPageStagedGrants.ts.

Backwards compatibility

The key is new and optional. An app that does not declare it, a gateway that predates it (no grant row) and every existing window get exactly what they had. Mochi's shell code does not read the grant, so Mochi behaves as before.

Breaking: an app record still stored as "approve what is declared" (an install from before approved sets that the gateway has not read since the upgrade) no longer approves an explicit-only family (point_grants.explicit_only_grant_families(): reachableByUserSessions and the new key) when its first read freezes it. Those wait on the app page's "Approve new permissions", because no owner was shown them before approved sets existed. A set already frozen or stored is untouched. No current user loses a working app session: reachableByUserSessions ships only in v0.13.0-rc.1, whose first read already froze such a record with its declared verbs into a stored set this change leaves alone, and on stable 0.12.x the key grants nothing to lose. Writer sweep on origin/main @ 6c8b798: _import_app_tree_grants in apps/manager_records.py is the only production writer of approveDeclared (_write_approve_declared has test callers only); the protected grant store has no writer outside the gateway.

Reader: src/kiro_crew/apps/user_session_reach.py:_approved -- chat -- test_a_record_from_before_approved_sets_approves_none_of_them
Reader: src/kiro_crew/apps/desktop_capabilities.py:_approved -- app -- test_a_record_from_before_approved_sets_approves_none_of_them

Tests

  • test/test_app_desktop_capabilities.py: the parse, the explicit-only family, catalog and CLI disclosure, install approving, an update staging and the owner approving, a pre-key set approving none, a record from before approved sets approving no explicit-only family when frozen (apps/manager_records.py:_freeze_declared), Mochi's declaration, a built-in approved as packaged.
  • test/test_builtin_adoption_pins.py: the key maps to level 7.
  • website/electron/test/app-window-host.test.js: refused when undeclared, staged or on a gateway with no grant row; localFiles and screenCapture served only to the holding app; withdrawal closes the window; choosing a crew moves the windows there and back; app off there falls back; a non-answer keeps them; a crew whose manifest lacks the window keeps it here; a stored crew that does not answer at start opens on this computer, then moves once it answers; a crew that gave up its port inside the 60 s reuse is never sent its token, neither by a newly opened window nor by the next tick; a crew's window holds only what the crew also approved (no screen, no file calls otherwise), reopens holding a capability the crew approves, and closes when the crew withdraws it; a window added here inside the 60 s reuse is checked against the crew's manifest, so a crew still on the older one leaves the windows on this computer; a crew that has not approved gatewayChoice never takes the windows, and the page there can still choose.
  • app-window-gateways.test.js: every connect is connected-only; a crew disconnected after the listing, whose manifest lacks one of this computer's windows, or whose owner has not approved gatewayChoice there falls back to this computer; confirm reads a crew as itself only while core shows it connected on the same port; a crew's target carries what the app declares and approved there, nothing else. app-local-files.test.js, app-window-host-rules.test.js, app-window-preload.test.js, app-window-host-independence.test.js.
  • TrustAppModalWorkerAutoApprove.test.tsx, AppDetailPageCoverage.test.tsx: disclosure, staged line, approval payload, trust target.

Mutation check: removing either port re-check (before a remote load, or on the tick) reds exactly its own new host test.

Determinism: the Python file 30x -n0, once shuffled (seed 4207), and -n 4 --dist loadgroup --max-worker-restart=2, green. The Electron gateway and host files 5x green (node 22 has no shuffle flag; the host tests wait on the host's own pending loads, never a timer). Vitest files 5x with --sequence.shuffle, green.

Local gates on this head: isort, flake8, black gate, mypy src/kiro_crew (clean), comment-history, brand, file-line cap, harness parity, docs-lint, the flake-pattern ratchet, tsc -p tsconfig.app.json, eslint on changed files, 4,602 related backend tests, 13 related Vitest files (298 tests), and the app-* and Mochi Electron files (375 of 376; petOverlays.test.js cannot load electron, which this host's node_modules lacks). Mutation check: dropping the gatewayChoice requirement on a crew reds the new host test and the resolver's definite-no cases; serving a crew's window this computer's set reds the both-gateways host test; reusing a crew target across a changed window set reds the window-added test. Semgrep is not installed on this host; CI's SAST runs it.

Manual verification

Rendered the trust prompt and the app page from a built bundle with stubbed APIs (screenshots below). The Electron windows themselves were exercised through the host's injected-Electron tests only; no live desktop session was run.

Screenshots / video

Trust prompt for an app declaring all three:

trust prompt

App page with one capability held back by an update:

app detail

Related Issues

Part of #26967

Owner ruling: #26967 (comment)

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

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

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing blocks: the three seams reuse the existing explicit-only grant family, the shell serves only what is both declared and approved, and the one take-away is listed as Breaking.

Notes

  • The _freeze_declared change also tightens reachableByUserSessions, not only the new key. The description lists it as Breaking and gives a reason, but it is a separate behaviour change and would be easier to revert as its own commit.
  • app-window-gateways.js sends core's token to tunnels this app chooses. The "re-read the registry before every load" rule is the only thing stopping a token reaching a port another crew took over, so keep that check in one place rather than repeating it at each load or reload site.

[DESIGN-REVIEWED] bbcd433

Description read

[DESCRIPTION-READ] 27973713423b61e6efaaf88fd73706e68bfdbc0d303634a09a5155fa5cab946d

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 13, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of bbcd43358b4660ad9b9c54cf7ca618976153dbfc — 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 traces back to the #26967 owner ruling or to a documented invariant. The one note is a gateway-switcher copy that has to exist until Mochi's shell code leaves core.

Notes

  • Item 3 — duplicate of website/electron/mochi/index.js instance switcher (/api/instances listing plus /connect token, lines ~198–413): app-window-gateways.js is a second copy of it, while the local-file rules were merged into one (mochi-pet:open-image / mochi-panel:reveal-file now call app-local-files.js). The description's "Not a goal: Changing what Mochi's shell code does today" covers this. Subtraction: delete Mochi's switcher in the PR that moves Mochi onto the host, so app-window-gateways.js is the only copy left.

What this change ships

Inventory (9 items) — 8 justified

Intent: let an external desktop app's own windows capture the screen, reveal or open local files and switch gateways, but only when the app declares it and the owner approves it, so Mochi can leave core. ADDITION.

  1. App windows can capture the screen when the app declares screenCapture and the owner approves it — justified
  2. App windows can reveal a local file or open a local image (localFiles) — justified
  3. App windows can list the operator's crews and move to one of them (gatewayChoice) — duplicate of Mochi's instance switcher, deferred
  4. The trust prompt, the CLI install summary and the catalog now show the desktop capabilities an app asks for — justified
  5. The app page offers a held-back capability under "Approve new permissions" — justified
  6. A pre-approved-sets record no longer approves an explicit-only family (including reachableByUserSessions) when it is frozen — justified
  7. Mochi's manifest declares the three capabilities, with no change in what Mochi does — justified
  8. Mochi's reveal/open handlers now use the shared app-local-files.js rules — justified
  9. The new key maps to App Kit seam level 7 in adoption_pin.py — justified

[FIRST-PRINCIPLES-REVIEWED] bbcd433

Description read

[DESCRIPTION-READ] 54a112952b9231bd995ff8167f6883b876d3790a7e06ee123e0086435cbfeb5f

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 13, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

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

UX-Verdict: PASS

Nothing blocks: both screenshots show the new capability lines, in the trust prompt and on the app page with a held-back permission, and the blind reader read them correctly.

Notes

  • desktop_capability_*: each of the three lines starts with "In the desktop app, its windows can…". Say it once in the heading (e.g. "In the desktop app, this app's windows can also:") and shorten the lines to "Capture your screen", "Show a file in your file manager and open an image" and "Switch to another of your crews".
  • DesktopCapabilitiesBox: on the app page only held-back permissions get a tag. The reader said "nothing says so" about the other two lines. Once one line shows "· not approved", tag the rest as approved too.

[UX-REVIEWED] bbcd433

Description read

[DESCRIPTION-READ] 3377add4753423dedfaa980d4a1546eda5b191b56e298077b4c7458e78e6266f

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] bbcd433

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

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

@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings (all downgraded on adjudication)

GPT 6.1 flagged blocking issues on bbcd43358b4660ad9b9c54cf7ca618976153dbfc; Opus 5.5 adjudication downgraded every one of them. Downgraded: the remedy each one needs is disproportionate to the harm it prevents. Adjudication downgraded all 1 blocking finding(s): the remedy each one requires is disproportionate to the harm it prevents.

This comment is updated in place on each push.

Review details

BLOCKING -- website/electron/app-window-host.js:1080 -- Failed revalidation opens newly declared windows on an unchecked crew

if (resolved.keep) return;
Trigger: A local app update adds an openOnEnable window while its existing windows run on a crew with the older manifest, and the crew’s manifest probe times out. resolveTargets retains the old target; reconcileTick still calls apply(next), which opens the added window there. loadPage confirms only the crew’s port, not its window declarations.
Outcome: DesktopWindowPage closes the unsupported window. Subsequent ticks reopen it on the same unchecked crew, so the new desktop feature remains unavailable and its window repeatedly opens and closes.
Anchor: defect
Fix: Preserve existing windows on a non-answer, but gate new window creation against the target’s validated window IDs until revalidation succeeds.
Sites: website/electron/app-window-host.js:1033 (automatic opening), website/electron/app-window-host.js:1039 (background reopening), website/electron/app-window-host.js:923 and website/electron/app-window-host.js:926 (shortcuts), website/electron/app-window-host.js:1187 (IPC opening), website/electron/app-window-host.js:244 (spanning copies).
[BLOCK-MERGE-DOWNGRADED] bbcd433
[GPT-REVIEWED] bbcd433

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

F1: harm is LOW. It needs four things at once: an app holding gatewayChoice pointed at a remote crew (app-window-host.js:1066), a local update that changes its window IDs so the held target can't be reused (:1072-1074), a crew probe that comes back as a non-answer (app-window-gateways.js:187-195), and the stale target kept (app-window-host.js:1080). The result is visible: a window opens and closes. It fixes itself, because windowKey no longer matches, so every 5 s tick (:66, :1343) calls gateways.resolve again (:1079) and picks the right target as soon as the crew answers. Nothing is lost and no security boundary is involved.
The real fix costs more than that: new per-target state for "validated window IDs", checked at the six open sites the finding lists (:244, :923, :926, :1033, :1039, :1187). That is a new rule every opener must follow, added for one transient path.

[ADJUDICATION] bbcd43358b4660ad9b9c54cf7ca618976153dbfc total=1 uphold=0 downgrade=1
DOWNGRADE F1 website/electron/app-window-host.js:1080 reason=disproportionate-remedy
[GPT-ADJUDICATED] bbcd43358b4660ad9b9c54cf7ca618976153dbfc

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

@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: connected-only connect on the shell's gateway resolver

  • Gateway polling reopens a tunnel the operator just disconnected span=1f0dd8aea945

fixed in 8abdba1: connect() in website/electron/app-window-gateways.js now posts /api/instances/<id>/connect?only_if_connected=1, so core checks the tunnel under its manager lock and declines (200, code: instance_not_connected) instead of reconnecting; that body already reads as "not usable" and falls back to this computer.
Class swept: this resolver's connect() is the only connect the PR adds (both resolve() and listFresh() go through it). Mochi's own connectInstance in mochi/index.js is unchanged main code driven by an explicit user pick, outside this diff.
Pinned: app-window-gateways.test.js routes every case through the connected-only path and adds "disconnected after the listing" falling back to self.

@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: connected-only connect on the shell's gateway resolver

  • shell connect() reaches core's tunnel connect without only_if_connected span=f9fb335261ac

fixed in 8abdba1: connect() now calls /api/instances/<id>/connect?only_if_connected=1; a declined 200 whose state is not connected is read as a definite "not usable" and falls back to self, matching the viewport auto-warm.
Both callers (resolve() per reconcile tick, listFresh() per listing) share that one connect(), so the whole class is covered; app-window-gateways.test.js pins the URL on every case and adds the disconnect-after-listing case.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • "Gateway" capability line stops people from approving span=08091ad66597

fixed in 8abdba1: the line no longer says "gateway" or "SSH". It reads "Its desktop windows can switch to another Kiro Crew you run, on this computer or a remote one." (product name via {{productName}}), in all 12 languages.
One sentence per capability on both surfaces: desktopCapabilityLine in components/appstore/desktopCapabilities.ts feeds the trust prompt, the app page box and the "Approve new permissions" notice; the separate pages.appDetailPage.desktop_capability_* strings are gone.
The trust-prompt heading now says trust grants them: "Trusting the app also grants its desktop windows these desktop app features". Fresh screenshots of both surfaces are in the description.

@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
@bolichen97
bolichen97 force-pushed the feat/w5-desktop-mochi branch from 8abdba1 to a9de3df Compare November 13, 2026 06:03
@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: remote window-declaration check before moving an app's windows

  • A remote app missing the requested window replaces working local windows span=1f0dd8aea945

fixed in a9de3df: appEnabledOn now parses the remote /api/apps body with the host's own desktopDeclarations and answers "enabled" only when the app there declares every window id this computer opens; otherwise it is a definite no and the windows stay on self.
Class swept: both readers of that answer take the ids. resolve(app, choice, windowIds) (reconcile) and list(app, windowIds) (the page's appEnabled, cache keyed by the id set) are passed the local declaration's ids from app-window-host.js.
Same span as round 1 by path only: a different defect in the same file, not a repeat of the connect fix.
Pinned: two gateway cases (older manifest lacking the window, no desktop block there) and a host test where choosing such a crew returns ok: false and leaves the local window open; both fail with the check removed.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • The gateway-choice permission can't be understood, so owners won't approve it span=aa33243e39e3

fixed in a9de3df: the line uses the product's crew vocabulary ("Switch crew", "Remote crews"): "In the desktop app, its windows can switch to another of your crews, on this computer or a remote one." The product name is no longer used as a countable noun.
The note matches: "Only from this app's own windows. The app never gets the keys used to reach your other crews." Each locale uses its existing word for crew.
The heading Note is taken too: "Trusting the app also allows the following", with "desktop" said once per line. One shared sentence per capability still feeds both surfaces; fresh screenshots are in the description.

@KiroCrewCaptain

KiroCrewCaptain commented Nov 13, 2026 •

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: A person should decide

Why: the decider thinks the change is probably fine but estimates a 20% chance that this change introduces a defect, above the 12% limit for approving on its own.

Adds permissions.desktopCapabilities (screenCapture, localFiles, gatewayChoice) as an explicit-only staged grant family, disclosed at install and on the app page and approved through the existing owner-gated consent path, which loops over every registered family. The Electron window host serves a capability only when the app declares it and the owner approved it, re-checked on every call. A window served by a remote crew gets only what both gateways approved. Remote tokens come from core's connected-only connect, and the crew's port is re-confirmed against core's registry before every remote load. Local-file rules are unchanged and now shared with Mochi. The _freeze_declared tightening is disclosed as Breaking and tested. The tests are extensive. The remaining issue found (stale target kept when a crew doesn't answer, causing window flapping) is low-harm and self-healing, so non-blocking. Approve, with CI still to go green.

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 bbcd43358b · 2491 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 13, 2026
@bolichen97
bolichen97 force-pushed the feat/w5-desktop-mochi branch from a9de3df to 70fac54 Compare November 13, 2026 07:41
@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: no
mechanism: explicit-only families take nothing when a legacy approveDeclared record is frozen

  • Legacy grant migration approves capabilities without owner consent span=c6d68d429b80

fixed in 70fac54: _freeze_declared in apps/manager_records.py now gives every explicit-only family (point_grants.explicit_only_grant_families()) an empty list when it freezes an approveDeclared record, instead of the manifest's declaration; other families keep what they granted until now. Built-ins never reach the freeze (they store their packaged set at start).
Class swept: the freeze is the one place an explicit-only family could inherit a declaration (the parsed path already empties a missing one in _parse_approved_grants), so this also closes it for reachableByUserSessions, which main shipped with the same gap. The PR body's Backwards compatibility names that as Breaking: with readers and the writer sweep.
Pinned: test_a_record_from_before_approved_sets_approves_none_of_them declares screen capture and session reach, writes the legacy record, and asserts both read as staged and the frozen set holds [] for every explicit-only family; it fails with the fix reverted.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Nov 13, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: a crew is a window target only where the app also holds gatewayChoice there

  • span=3238aa15c920 a crew without gatewayChoice traps the app's windows there

fixed in feaf406: appEnabledOn in app-window-gateways.js reads a crew whose owner has not approved gatewayChoice for the app (an older build with no grant row included) as a definite no, so resolve falls back to self and list shows that crew as appEnabled: false.
The windows never move to a crew that would serve them without chooseGateway, so the page always keeps its way back; the both-gateways intersection from the earlier round stays, a crew's bundle still gets no capability its own owner did not approve.
Class sweep: resolve and list both admit a crew through appEnabledOn, the one site fixed; servedCapabilities/holding only act on an admitted target.
Tests: app-window-host.test.js "a crew that has not approved gatewayChoice never takes the windows, so they can always come back" and two definite-no cases in app-window-gateways.test.js; both red with the new check removed. Spec and manifest reference updated.

@bolichen97

Copy link
Copy Markdown
Contributor Author

Moved onto origin/main 6de8528 (#37171), which fixes the main red test/tracing/test_tracing_otlp.py::test_the_exit_flush_sends_spans_still_queued and ::test_a_traced_turn_reaches_a_loopback_receiver_with_its_vault_header that failed Backend Tests (3.12, 2) and (Windows) (2) on feaf406 (tracing, not touched here; 175 passed locally on the new head). The Windows (8) red was test_dashboard_save_tool_older_rule.py::test_two_first_saves_at_once_bind_one_package, recorded on its ledger #37114. CodeQL javascript failed on the installation API rate limit at upload. New head a6eccfa: same diff, the locale files auto-merged and pass i18n:check / lint:i18n.

@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 14, 2026
An app's hosted desktop window could only shape its own windows. Mochi
needs three shell features (screen capture for its snip, reveal and
open a local file, and choosing among the operator's gateways), so it
could not move onto the window host.

permissions.desktopCapabilities names them (screenCapture, localFiles,
gatewayChoice). It is an explicit-only staged grant family: an install
approves what it declares, an update that adds one waits for the owner,
and the trust prompt, catalog projection, detail page and CLI summary
show it. The app row carries desktopCapabilitiesGrant, and the shell
serves declared and approved only. The window host (bridge level 2)
registers a screenCapture window as a capture surface, serves
revealFile/openImage through the new shared app-local-files.js, and
lists and switches crews through app-window-gateways.js, which rides
only tunnels core reports connected and loads a crew only where the
same app is enabled. A reused crew is re-read from core's registry on
every tick and before any window loads from it, so a crew that gave up
its local port is never sent its token. A window whose served set
changes is closed.

Mochi's manifest declares the three it already uses, and its reveal
and open-image handlers run the shared module. The manifest key shares
App Kit seam level 7 with the other seams of this release.

Part of #26967
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in src/kiro_crew/apps/permissions.py, docs/app-kit/api-reference.md, docs/feature-map/README.md, docs/system-specs/modules/app-kit-platform.md (+the locale files) since this head went green (6a61c84 -> 02e103f); CI re-running.

@bolichen97
bolichen97 force-pushed the feat/w5-desktop-mochi branch from a6eccfa to bbcd433 Compare November 14, 2026 13:31
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: passed Eligible automated validation passed for the current revision readiness: checking Automated validation is still running labels Nov 14, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: no

  • span=425976e6ecb7 failed revalidation opens newly declared windows on an unchecked crew

Rebutted (disproportionate, not a defect in any boundary): the path needs a gatewayChoice app on a crew, a local update that changes its window ids, and a crew probe that does not answer, all at once; the only effect is the added window opening and closing.
It heals itself: the changed windowKey keeps the held target from being reused, so every tick calls gateways.resolve again and the first answer either confirms the crew's manifest or falls back to self.
No credential, file or capability crosses: loadPage still re-confirms the crew's port before any load, and the crew's own page refuses a window its manifest does not declare.
The fix would add per-target "validated window ids" state checked at six open sites for one transient path; Opus 5.5 adjudication on this head downgraded it for the same reason. Span answered in earlier rounds by the reuse-window and port checks; this round changes nothing there.

@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 these points:

  • The new desktopCapabilities family is explicit-only. _freeze_declared gives explicit-only families nothing when it freezes a legacy approveDeclared record. The Breaking note for reachableByUserSessions matches the tags.
  • The shell serves only declared ∩ approved, at every read. A window a crew serves gets only what both gateways approved.
  • A crew's token goes to a port only after core's registry still shows that crew connected there.
  • Mochi's runtime is unchanged, because it has no desktop block.
  • The new Electron host, gateway and local-file tests passed three runs in a row. Each mutation named in the body reds the test it names.

Done well: the local-file rules now live in one module. Mochi's handlers and the new host both use it, with the same checks in the same order.

Security: the new capabilities give apps screen capture, local file reveal and open, and gateway choice. An app gets them only through the existing owner consent path, and they are shown at install and on the app page. Windows served from a remote crew hold only the capabilities approved on both gateways. The one blocking lane finding was downgraded on adjudication. It covers a crew that does not answer, which can open an added window on a crew whose manifest was not checked. No credential leaks: the port is confirmed again before the load, and the token goes to the same crew. The next answering tick moves the windows back.

Optional:

  • website/electron/app-window-host.js:1248: revealFile, openImage and chooseGateway do not require a user action, unlike openExternal, which uses actingSender. A background window could call them on a timer. You could gate them the same way, or say in the spec why an unattended page may call them.
  • website/electron/app-window-host.js:398: void reconcileOnce() joins the tick already running, so the re-resolve waits for the next 5 s tick. reconcileAfterCurrent() would make it happen "at once", as the comment says.
  • Two test gaps. No test covers the non-answer branch at :1080 that the resolveTargets docstring describes. No test asserts the capture-trust origin for a crew-served screenCapture window (:640). The reuse-window tests could also pass now instead of setting _targets.get(...).at.

@bolichen97
bolichen97 merged commit 693e3be into main Nov 14, 2026
156 of 157 checks passed
@bolichen97
bolichen97 deleted the feat/w5-desktop-mochi branch November 14, 2026 15:28
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 14, 2026
bolichen97 added a commit that referenced this pull request Nov 15, 2026
The desktop window host gave an app fixed manifest accelerators and no
per-machine state, so a desktop pet could not move onto it: its users
rebind its global shortcuts, its defaults differ per platform, its
shell code reserves its chords even while disabled, and the crew it
shows plus the rebinds live in a shell store a window page cannot read
(#36349 left the shortcut gap under "Not a goal").

Generically, with the app id as data:

- desktop.shortcuts[].platformAccelerators: a per-platform default,
  held to the same chord rules (gateway and shell); seam level 8.
- The host binds the user's chord per app per machine, and a page's
  shortcuts() / setShortcut() (bridge level 3) lists and rebinds only
  the app's declared shortcuts, only right after a press in that
  window, and onto a chord other than the declared default only when
  the user pressed that chord there; bound first and kept only when it
  registered.
- prefs() / setPref(): each app's own small prefs on this computer,
  whichever gateway serves the window, bounded in size and in writes
  (32 at once, then one per 250 ms); the store is held in memory, so
  reads touch no disk.
- A shell owner that is an app's own shell code reserves { app: true }
  and the host serving that app id may bind those chords; Mochi's
  reservation is marked so.
- desktop.legacyMachinePrefs: a one-time, read-only import of the
  built-in's <app>-machine.json (a regular file of at most 256 KiB, a
  link not followed) into the host store, before the targets resolve,
  seeding the gateway choice and the bindings, never overwriting what
  the host has.

Built-ins behave as before: no built-in declares a desktop block, so
the host serves none of them yet.

Part of #26967
bolichen97 added a commit that referenced this pull request Nov 15, 2026
The desktop window host gave an app fixed manifest accelerators and no
per-machine state, so a desktop pet could not move onto it: its users
rebind its global shortcuts, its defaults differ per platform, its
shell code reserves its chords even while disabled, and the crew it
shows plus the rebinds live in a shell store a window page cannot read
(#36349 left the shortcut gap under "Not a goal").

Generically, with the app id as data:

- desktop.shortcuts[].platformAccelerators: a per-platform default,
  held to the same chord rules (gateway and shell); seam level 8.
- The host binds the user's chord per app per machine, and a page's
  shortcuts() / setShortcut() (bridge level 3) lists and rebinds only
  the app's declared shortcuts, only right after a press in that
  window, and onto a chord other than the declared default only when
  the user pressed that chord there. The new chord is registered
  before the binding moves, so a refused rebind or reset keeps the
  chord the app held and never frees it for another app.
- A shell owner that is an app's own shell code reserves { app: true }
  and the host serving that app id may bind those chords; Mochi's
  reservation is marked so.
- desktop.legacyMachinePrefs: a one-time, read-only import of the
  built-in's <app>-machine.json (a regular file of at most 256 KiB, a
  link not followed) into the host store, before the targets resolve,
  seeding the gateway choice and the bindings and reading no other
  key, never overwriting what the host has or a gateway the user chose
  through the host while the import was pending ("self" included).

Built-ins behave as before: no built-in declares a desktop block, so
the host serves none of them yet.

Part of #26967
bolichen97 added a commit that referenced this pull request Nov 15, 2026
The desktop window host gave an app fixed manifest accelerators and no
per-machine state, so a desktop pet could not move onto it: its users
rebind its global shortcuts, its defaults differ per platform, its
shell code reserves its chords even while disabled, and the crew it
shows plus the rebinds live in a shell store a window page cannot read
(#36349 left the shortcut gap under "Not a goal").

Generically, with the app id as data:

- desktop.shortcuts[].platformAccelerators: a per-platform default,
  held to the same chord rules (gateway and shell); seam level 8.
- The host binds the user's chord per app per machine, and a page's
  shortcuts() / setShortcut() (bridge level 3) lists and rebinds only
  the app's declared shortcuts, only right after a press in that
  window, and onto a chord other than the declared default only when
  the user pressed that chord there. The new chord is registered
  before the binding moves, so a refused rebind or reset keeps the
  chord the app held and never frees it for another app.
- A shell owner that is an app's own shell code reserves { app: true }
  and the host serving that app id may bind those chords; Mochi's
  reservation is marked so.

For Mochi, its own shell code (mochi/hostHandOff.js, called from
initMochi before the host is created) copies the crew the pet shows
and the user's rebinds from mochi-machine.json into the host's gateway
choice and bindings for mochi, recording what it copied. It copies
again only while the host still holds that value, so a change in the
built-in before adoption carries over and a choice made through the
host is never overwritten. It leaves core with Mochi's shell code.

Built-ins behave as before: no built-in declares a desktop block, so
the host serves none of them yet.

Part of #26967
bolichen97 added a commit that referenced this pull request Nov 15, 2026
The desktop window host gave an app fixed manifest accelerators and no
per-machine state, so a desktop pet could not move onto it: its users
rebind its global shortcuts, its defaults differ per platform, its
shell code reserves its chords even while disabled, and the crew it
shows plus the rebinds live in a shell store a window page cannot read
(#36349 left the shortcut gap under "Not a goal").

Generically, with the app id as data:

- desktop.shortcuts[].platformAccelerators: a per-platform default,
  held to the same chord rules (gateway and shell); seam level 8.
- The host binds the user's chord per app per machine, and a page's
  shortcuts() / setShortcut() (bridge level 3) lists and rebinds only
  the app's declared shortcuts, only right after a press in that
  window, and onto a chord other than the declared default only when
  the user pressed that chord there. The new chord is registered
  before the binding moves, so a refused rebind or reset keeps the
  chord the app held and never frees it for another app.
- A shell owner that is an app's own shell code may reserve
  { app: true } so the host serving that app id may bind those chords.
  Mochi keeps a plain reservation until its built-in steps aside
  (#37454), so the two never register the same chords. One binding is
  one chord whatever its spelling, so a respelled rebind keeps the
  chord with its holder.

For Mochi, its own shell code (mochi/hostHandOff.js, called from
initMochi before the host is created) copies the crew the pet shows
and the user's rebinds from mochi-machine.json into the host's gateway
choice and bindings for mochi, recording what it copied. It copies
again only while the host still holds that value, so a change in the
built-in before adoption carries over and a choice made through the
host is never overwritten. It leaves core with Mochi's shell code.

Built-ins behave as before: no built-in declares a desktop block, so
the host serves none of them yet.

Part of #26967
bolichen97 added a commit that referenced this pull request Nov 15, 2026
The desktop window host gave an app fixed manifest accelerators and no
per-machine state, so a desktop pet could not move onto it: its users
rebind its global shortcuts, its defaults differ per platform, its
shell code reserves its chords even while disabled, and the crew it
shows plus the rebinds live in a shell store a window page cannot read
(#36349 left the shortcut gap under "Not a goal").

Generically, with the app id as data:

- desktop.shortcuts[].platformAccelerators: a per-platform default,
  held to the same chord rules (gateway and shell); seam level 8.
- The host binds the user's chord per app per machine, and a page's
  shortcuts() / setShortcut() (bridge level 3) lists and rebinds only
  the app's declared shortcuts, only right after a press in that
  window, and onto a chord other than the declared default only when
  the user pressed that chord there. The new chord is registered
  before the binding moves, so a refused rebind or reset keeps the
  chord the app held and never frees it for another app.
- A shell owner that is an app's own shell code may reserve
  { app: true } so the host serving that app id may bind those chords.
  Mochi keeps a plain reservation until its built-in steps aside
  (#37454), so the two never register the same chords. One binding is
  one chord whatever its spelling, so a respelled rebind keeps the
  chord with its holder.

For Mochi, its own shell code (mochi/hostHandOff.js, called from
initMochi before the host is created) copies the crew the pet shows
and the user's rebinds from mochi-machine.json into the host's gateway
choice and bindings for mochi, recording what it copied. It copies
again only while the host still holds that value, so a change in the
built-in before adoption carries over and a choice made through the
host is never overwritten. It leaves core with Mochi's shell code.

Built-ins behave as before: no built-in declares a desktop block, so
the host serves none of them yet.

Part of #26967
bolichen97 added a commit that referenced this pull request Nov 15, 2026
The desktop window host gave an app fixed manifest accelerators and no
per-machine state, so a desktop pet could not move onto it: its users
rebind its global shortcuts, its defaults differ per platform, its
shell code reserves its chords even while disabled, and the crew it
shows plus the rebinds live in a shell store a window page cannot read
(#36349 left the shortcut gap under "Not a goal").

Generically, with the app id as data:

- desktop.shortcuts[].platformAccelerators: a per-platform default,
  held to the same chord rules (gateway and shell); seam level 8.
- The host binds the user's chord per app per machine, and a page's
  shortcuts() / setShortcut() (bridge level 3) lists and rebinds only
  the app's declared shortcuts, only right after a press in that
  window, and onto a chord other than the declared default only when
  the user pressed that chord there. The new chord is registered
  before the binding moves, so a refused rebind or reset keeps the
  chord the app held and never frees it for another app.
- A shell owner that is an app's own shell code may reserve
  { app: true } so the host serving that app id may bind those chords.
  Mochi keeps a plain reservation until its built-in steps aside
  (#37454), so the two never register the same chords. One binding is
  one chord whatever its spelling, so a respelled rebind keeps the
  chord with its holder.

For Mochi, its own shell code (mochi/hostHandOff.js, called from
initMochi before the host is created) copies the crew the pet shows
and the user's rebinds from mochi-machine.json into the host's gateway
choice and bindings for mochi, recording what it copied. It copies
again only while the host still holds that value, so a change in the
built-in before adoption carries over and a choice made through the
host is never overwritten. It leaves core with Mochi's shell code.

Built-ins behave as before: no built-in declares a desktop block, so
the host serves none of them yet.

Part of #26967
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