Skip to content

docs(computer-use): record the macOS check-to-launch window as a shortcut - #32811

Merged
buluoray merged 1 commit into
mainfrom
crew/slack/macos-launch-pin
Nov 11, 2026
Merged

buluoray merged 1 commit into
mainfrom
crew/slack/macos-launch-pin

Conversation

@buluoray

@buluoray buluoray commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Record the macOS check-to-launch bundle-swap window in computer_launch_app as an accepted, documented shortcut, with launch behaviour unchanged from main.

A stock /Applications is drwxrwxr-x root admin, so _writable_component skips the parent probe there and judges the bundle by its own directories. But every admin user can still rename an entry in it. Between resolve_target (the verification) and spawn_detached (/usr/bin/open -a <path>), run_launch runs the policy check and the running-app lookup. An agent's shell child running at the same time can rename the verified, root-owned bundle aside and put its own bundle at the same path, and open -a then launches agent-written code outside the agent sandbox. Found by GPT on the 0.12.1 port of #31408 (#32791); the same code is on main.

Why it matters

The launch check exists so the agent cannot use this verb to run code it wrote. This gap reopens that for every admin user (the default for a Mac's main account).

Not a goal

  • Changing which bundles pass verification, or the stock /Applications rule.
  • Closing the milliseconds between the final check and LaunchServices reading the bundle (see Backwards compatibility and the shortcut: comment).
  • Windows, which resolves through its own catalog.

What changed (motivation → approach → change)

The first heads closed the window with a bundle fingerprint and three new refusals. The maintainer asked for the opposite direction in this review: the repo does not take added security strictness on this launch path, so the launch behaves as on main and the window is recorded as an accepted, documented shortcut instead.

The diff is now 12 added lines:

  • src/kiro_crew/computer_use/launch_macos.py: a shortcut: comment in spawn_detached naming the check-to-launch window (the launch goes by path; an admin user can swap the bundle at that path before LaunchServices reads it) and its upgrade (launch by a file reference held from the check to the spawn).
  • docs/system-specs/modules/computer-use.md: one paragraph recording the window as accepted, and that closing it means a file-reference launch, not a refusal on top of the path launch.

No fingerprint, no _verified_bundles, no new refusal, no test change. resolve_target and spawn_detached behave exactly as on main.

Backwards compatibility

Compatible: no code path changes; only a comment and a spec paragraph are added.

Removes nothing.

Tests

Proof: not provable -- other: comment and spec only, no behaviour change

  • test/test_computer_use_launch.py and test/test_computer_use_launch_macos_stock.py are unchanged from main and pass (108 passed, 7 skipped).
  • scripts/docs-lint.sh, the comment-history and brand gates pass.

Manual verification

N/A - no behaviour change.

Screenshots / video

N/A - no frontend file changes.

Related Issues

Refs #31408, #32791.

Sibling sweep

Siblings: none -- the only check-to-launch path on macOS is spawn_detached; Windows resolves through its own catalog.

Pattern harvest

Not generalizable: a single documented shortcut.

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.

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

github-actions Bot commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

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

@github-actions

github-actions Bot commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 0e85f34dd28eb3f69834d16c03495841a1cd115c — 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 change adds only a comment and a spec paragraph, and launch behaviour is the same as on main.

Notes

What this change ships

Inventory (2 items) — 1 justified

Intent: Record the macOS window between the bundle check and the launch as an accepted, known risk, without changing how the launch works. This is an ADDITION (documentation only).

  1. The computer-use spec now says the check and the launch are separate steps, and that the bundle-swap window between them is accepted — inherited (the defect is asserted, not reproduced)
  2. spawn_detached gets a shortcut: comment naming the window and how to close it later — justified

[FIRST-PRINCIPLES-REVIEWED] 0e85f34

Description read

[DESCRIPTION-READ] cce4586d7d8e44cded1386d12288a2cb9db2b54b57ac2d35f7729c9246f2cb7a

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

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing blocks: only a comment and a spec paragraph change, launch behaviour is the same as on main, and a maintainer asked for this direction.

Notes

  • The description says the window lets agent-written code launch outside the sandbox for every admin user. An accepted escape like that should have a tracking issue for the file-reference launch, not just the shortcut: comment.

[DESIGN-REVIEWED] 0e85f34

Description read

[DESCRIPTION-READ] 18595b5271e83b8cbb80cf00b746b3e115694a603de94819976b48f34dcda9e1

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

Comment-only and doc-only changes. Nothing executable changed.

No findings.

[OPUS-REVIEWED] 0e85f34

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

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

@github-actions

github-actions Bot commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 0e85f34

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

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 8, 2026
@buluoray
buluoray force-pushed the crew/slack/macos-launch-pin branch from 1feecf7 to cba1804 Compare November 8, 2026 01:21
@buluoray

buluoray commented Nov 8, 2026

Copy link
Copy Markdown
Contributor Author

span=88452e2064fb
🤖 Kiro Crew Auto-Pipeline [operator: buluoray]:

  • Fixed in cba1804. resolve_target now reads _bundle_fingerprint BEFORE _writable_component, refuses unless the fingerprint is non-None and unchanged after the check, and pins only that pre-check identity. New test test_a_bundle_swapped_in_DURING_the_check_is_never_pinned swaps the bundle inside the check: it goes red with the old fingerprint-after order (DID NOT RAISE) and green with the fix; computer-use.md describes the order.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Nov 8, 2026
@buluoray buluoray added the ci:macos Run the on-demand macOS suite against this PR head label Nov 8, 2026
@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 8, 2026
@buluoray

buluoray commented Nov 8, 2026

Copy link
Copy Markdown
Contributor Author

🤖 Kiro Crew Auto-Pipeline [operator: buluoray]: macOS evidence for the Design lane's "Clears when" on head cba1804: the full macOS suite ran on this head (ci:macos). It finished with 34999 passed and 1 failed, and every test/test_computer_use_launch*.py test passed on a real macOS runner. The one failure is test/test_cloud_ssm_cov80.py::TestInstallCommandHint::test_deb_one_liner_reaches_sudo_only_on_a_matching_download[True]. It fails because the runner's sha256sum is the BSD one (usage: sha256sum [-bctwz]). It is tracked as #32526 and this diff does not touch it.

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed head cba1804. The fingerprint code reads cleanly, but I'm requesting one change of direction.

This adds new refusals to the existing macOS launch path, and this repo does not take added security strictness. On main, a bundle that passes resolve_target's checks launches. This PR adds three refusals on top of that:

  1. resolve_target raises _ERR_BUNDLE_CHANGED when the _bundle_fingerprint read before _writable_component differs from the one after it, or when it is None (any of the fingerprinted files unreadable).
  2. spawn_detached raises OSError for any path not in _verified_bundles. That is new for a caller that hands it a path without going through resolve_target in this process.
  3. spawn_detached also raises when the path's fingerprint changed since the resolve. That would include a legitimate app update landing between the resolve and the launch.

Please drop _verified_bundles, _bundle_fingerprint, _ERR_BUNDLE_CHANGED and the three checks, so resolve_target and spawn_detached behave as on main, and move the new tests out with them. If you want the rename-and-replace risk recorded, a shortcut: comment in spawn_detached naming the window, plus the spec note, is welcome without the refusal.

Separately, macOS backend shard 6 is red on test/test_cloud_ssm_cov80.py::TestInstallCommandHint::test_deb_one_liner_reaches_sudo_only_on_a_matching_download[True] (a sha256sum usage error). This PR does not touch that file, so I am not counting it against the change.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: passed Eligible automated validation passed for the current revision labels Nov 8, 2026
@buluoray
buluoray force-pushed the crew/slack/macos-launch-pin branch from cba1804 to de740f0 Compare November 8, 2026 03:28
@buluoray buluoray changed the title fix(computer-use): launch only the macOS bundle that was verified docs(computer-use): record the macOS check-to-launch window as a shortcut Nov 8, 2026
@buluoray

buluoray commented Nov 8, 2026

Copy link
Copy Markdown
Contributor Author

🤖 Kiro Crew Auto-Pipeline [operator: buluoray]: @bolichen97 done in de740f0, following your direction. _verified_bundles, _bundle_fingerprint, _ERR_BUNDLE_CHANGED and all three refusals are gone, so src/kiro_crew/computer_use/launch_macos.py matches main apart from one shortcut: comment in spawn_detached naming the check-to-launch window and its upgrade (launch by a file reference). test/test_computer_use_launch.py and test/test_computer_use_launch_macos_stock.py are back to main. computer-use.md records the window as accepted. The PR is now 12 added lines in those two files, and the title is retitled to docs(computer-use): ... to match. The launch tests pass (108 passed, 7 skipped), as do docs-lint and the comment-history and brand gates.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 8, 2026
@buluoray

buluoray commented Nov 8, 2026

Copy link
Copy Markdown
Contributor Author

🤖 Kiro Crew Auto-Pipeline [operator: buluoray]: The frozen Goal was amended by a human maintainer, not by the pipeline. It now reads: "Record the macOS check-to-launch bundle-swap window in computer_launch_app as an accepted, documented shortcut, with launch behaviour unchanged from main." Why: @bolichen97's review asked to drop the fingerprint and the three new refusals, since this repo does not take added security strictness on this launch path. Head de740f0 does exactly that: it adds only a shortcut: comment in spawn_detached and a computer-use.md paragraph. The old Goal described the earlier closed-window direction, so the First Principles and Design lanes flagged the mismatch (spans 7779089a7b43, 39d6869c7d79). The Goal and the description now both describe the docs-only change, and both lanes are being rerun on this head.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 8, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving head de740f0. The refusals are gone, so resolve_target and spawn_detached behave as on main, and the window is recorded as a shortcut: comment in spawn_detached plus the spec paragraph.

The red macOS shard 6 is the BSD sha256sum test that #32915 fixed on main. Could you rebase onto main? The push will dismiss this approval, and I will re-approve once it is green.

…tcut

spawn_detached launches the bundle by the path resolve_target verified,
so an admin user can swap the bundle at that path between the checks
and LaunchServices reading it. The maintainer accepted that window as a
documented shortcut rather than a new refusal, so the launch path stays
as on main: a shortcut comment in spawn_detached names the window and
the upgrade (launch by a file reference), and computer-use.md records
it.
@buluoray
buluoray force-pushed the crew/slack/macos-launch-pin branch from de740f0 to 0e85f34 Compare November 11, 2026 15:15
@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: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 11, 2026
@buluoray
buluoray merged commit 5c6750e into main Nov 11, 2026
159 of 161 checks passed
@buluoray
buluoray deleted the crew/slack/macos-launch-pin branch November 11, 2026 17:30
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ci:macos Run the on-demand macOS suite against this PR head

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants