Skip to content

fix(service): probe launchd by domain target on macOS - #11016

Open
dwu96 wants to merge 1 commit into
mainfrom
fix/service-macos-domain-explicit-probe-11002
Open

dwu96 wants to merge 1 commit into
mainfrom
fix/service-macos-domain-explicit-probe-11002

Conversation

@dwu96

@dwu96 dwu96 commented Sep 15, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: On macOS, kirocrew service status and every is_active() caller see the gateway LaunchAgent while it is serving, instead of reporting "kirocrew service is not loaded (no entry)".

is_active() and status() probed with launchctl list <label>. That legacy form reads only the caller's domain, and for the gateway's gui/<uid> agent it exits non-zero with empty output while launchctl print gui/<uid>/<label> answers for the same label at the same moment (the reporter's measured rc pair in #11002). The "(no entry)" text is the empty-stderr fallback.

Why it matters

service status exits 1 and is_service_active() returns False for a running gateway, so anyone diagnosing a Mac gateway is told it is down, and any caller gated on that bit takes the no-service path.

Not a goal

What changed (motivation → approach → change)

Symptom: a serving gateway reads as not loaded. Root cause: the probes address the job by a different form (caller-domain list) than the verbs that act on it (named gui/<uid> then user/<uid>, since #17492). Fix: the probes use the same domains.

  • macos._probe() runs launchctl print <domain>/<label> over _legacy_domains() (gui/<uid>, then user/<uid>) and returns the first domain that answers rc 0. With none, it keeps the most telling refusal: a refusal other than "not found" / 125 wins.
  • is_active(): true when any domain answers rc 0, including loaded-but-not-running (the list-era contract). Any non-zero answer is inactive, unlike is_loaded(), which reads an unclear answer as loaded.
  • is_up() (new): true only for state = running. controller.service_status() exits on it, matching Linux's is_up(): a crash-looping agent (loaded, not running) exits 1, while is_active() keeps it reachable to stop.
  • status(): a terse summary instead of the ~3 KB print dump: <label>: <state> (<domain>), pid, last exit when non-zero and numeric, plist. Not loaded keeps the old message; its reason falls back to stdout's first line, then no entry.
  • Docstrings in macos.py, comments in controller.py, and docs/system-specs/modules/cli.md no longer say the probes read the caller's domain.

Since the first revision of this PR: rebased over #17492, _target() dropped for main's _legacy_domains(), and the probe now also finds a user/<uid> job, which closes the gap the Design Review named.

Backwards compatibility

Breaking: kirocrew service status on macOS now exits 1 for a loaded-but-not-running agent (the list probe exited 0 when the PID key was absent). Writer sweep on origin/main @ 2cf3d0d: the exit code is read only by cli_server's service status subcommand (returned as the process exit) and by scripts; no in-repo caller gates on it. is_service_active(), stop_service() and restart_service() do not use is_up().

Reader: src/kiro_crew/service/controller.py:service_status -- entry: release (CLI kirocrew service status) -- exits on macos.is_up(); test_service_status_exit_follows_running_not_loaded
Reader: src/kiro_crew/service/controller.py:is_service_active -- entry: release -- still macos.is_active() (loaded counts); test_status_and_is_active_see_the_gui_job_from_any_session

Tests

  • test/test_service_macos_control.py: fixtures migrated from list-shaped to print-shaped output. New: argv-discriminating probe tests (only print gui/<uid>/<label> answers, every other spelling fails empty, as reported), terse summary, last exit both spellings, numeric gate (0, -15, --78, superscripts), stdout reason fallback, no entry fallback.
  • test/test_service_macos_control.py also pins the exit-code split: running -> is_up True, exit 0; not running -> is_active True, is_up False, exit 1; nothing loaded -> is_up False. test/test_service_controller.py's two macOS status tests now patch is_up.
  • test/test_service_macos_launchd_domain.py (stateful launchctl stand-in from fix(service): address launchd gui/<uid> domain explicitly in install and stop #17492): status/is_active/service_status() see the gui job from a desktop and an SSH session; follow a no-desktop install into user/<uid>; see a legacy user/<uid> job from the desktop; nothing loaded reads inactive with the not-found reason, with and without a desktop; a real gui refusal is shown over a later user "not found". test_kirocrew_stop_from_ssh_boots_out_the_gui_job no longer pins the old miss.
  • Red on base: the new unit tests fail against main's macos.py. prove.py: PROVEN.
  • Determinism: 20/20 at -n0, 10/10 at -n 4 --dist loadgroup --max-worker-restart=2 with test_service.py and test_service_controller.py as co-tenants, shuffled order (seed 11016, 132 ids) green.
  • Local gate: flake8, isort, mypy, flake ratchet, semgrep clean; the related backend set has 15 failures that fail identically on a clean origin/main worktree on this host (test_cli.py doctor, test_cli_gateway_boot.py, test_terminal_handler.py, test_xdist_escaped_failure_guard.py), none in service code.

Manual verification

Not run on a Mac: this host is Linux. The print field spellings parsed (state, pid, path, last exit code / last exit status) and the rc semantics are the ones pod/launchd.py already parses on main; the reporter's measured list rc=1 / print rc=0 pair (#11002) is the live evidence. A live-launchd test was tried and dropped: the root conftest's host-service guard forbids tests that bootstrap real agents outside the opt-in e2e suites.

Related Issues

Closes #11002

Pattern harvest

Rule candidate: review-prompt
Pattern: a probe that addresses a service by a different form (caller-domain launchctl list) than the verbs acting on it (named <domain>/<label>) diverges on any host where the two resolve differently; probes must address the job the way its actuators do.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title
  • 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

@github-actions

github-actions Bot commented Sep 15, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] b2ed600

False positive or not applicable? A repository writer can comment:
/ai-review override gpt b2ed600440894ae0900310b78c2a005639219d13: <one-sentence reason>

@github-actions

github-actions Bot commented Sep 15, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] b2ed600

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

False positive or not applicable? A repository writer can comment:
/ai-review override fable b2ed600440894ae0900310b78c2a005639219d13: <one-sentence reason>

@github-actions

github-actions Bot commented Sep 15, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — 🔴 BLOCK (blocking)

Design-level review of b2ed600440894ae0900310b78c2a005639219d13 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: BLOCK

No one has run this on a Mac. The macOS-only probe now decides service status's exit code and is_service_active(), and the PR's only evidence is mocked fixtures.

Blockers

macOS-only branch has no manual verification

  • Cause: the description says "Manual verification — Not run on a Mac: this host is Linux."
  • Mechanism: service_status() now returns 0 if macos.is_up() else 1. is_up() depends on two things CI never sees from real launchd:
    • which domain answers launchctl print gui/<uid>/<label>, from a desktop session and from SSH;
    • the first top-level state = running line in that output.
  • Why it matters: is_active() feeds is_service_active(), which is the gate at cli_server_restart.py:732. The new tests feed in print output written by hand, and the reporter's rc pair checks only the return code, not the text being parsed.
  • Consequence: if real print output differs (a different domain answers, a nested state = line, or the wording), service status keeps telling Mac users a running gateway is down. That is the exact symptom this PR claims to fix, and nothing in the repo would catch it.
  • Fix: have a macOS user run it against a live LaunchAgent before merge.

Clears when: the PR description shows real output and exit codes of kirocrew service status on macOS for (a) a running agent from the desktop, (b) the same agent from SSH, and (c) an agent that is loaded but not running.

[DESIGN-REVIEWED] b2ed600

Description read

[DESCRIPTION-READ] cf63eae2c3ad49258b613881548ec54d374841c10aebbd5c08392c0b010a9389

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

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — 🟡 CONCERNS

Premise-level review of b2ed600440894ae0900310b78c2a005639219d13 — 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/CONCERNS are advisory.

First-Principles-Verdict: CONCERNS

The macOS service status exit-code change (1 for a loaded-but-not-running agent) rides along a probe fix, and its only support is matching Linux.

Not justified as shipped

  • Item 3 — rides along, inherited (symmetry): the only support given is "controller.service_status() exits on it, matching Linux's is_up()". The description itself says "Breaking". The reported defect (macOS: service status/is_active probe launchd with legacy launchctl list <label>, which fails for a gui-domain agent — a running gateway reports "not loaded (no entry)" #11002) is already fixed by items 1–2 on their own: is_active() now returns True for a not running agent, which is the old list-era contract. No issue reports a crash-looping Mac agent that showed as up.
    Subtraction: delete macos.is_up() and keep return 0 if macos.is_active() else 1 in controller.service_status. Drop the is_up tests and the cli.md "exit 0 only when … running" clause with it.
    Clears when: an issue or failing test shows a macOS script misreading a crash-looping agent as up, or a maintainer records the exit-code change as a decision.

What this change ships

Inventory (5 items) — 4 justified

Intent: On a Mac, see a serving gateway LaunchAgent as running, not "not loaded". FIX.

  1. kirocrew service status finds the serving gui/<uid> agent from desktop or SSH — justified
  2. is_service_active() and is_active() callers see a gui/ or user/<uid> job — justified
  3. service status exits 1 for a loaded-but-not-running agent (new is_up) — rides along, inherited symmetry with Linux
  4. service status output becomes a terse summary (state, domain, pid, last exit, plist) — justified
  5. The not-loaded reason prefers a real refusal over "not found", then falls back to the first stdout line — justified

[FIRST-PRINCIPLES-REVIEWED] b2ed600

Description read

[DESCRIPTION-READ] cab04fb5afa7937ca5b372b372cdf49cd263f883f5b7b4a7e9a7cc68f45e05ef

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 added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 15, 2026
@dwu96
dwu96 force-pushed the fix/service-macos-domain-explicit-probe-11002 branch from 7db57b4 to 5596730 Compare September 15, 2026 10:00
@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 Sep 15, 2026
@dwu96
dwu96 force-pushed the fix/service-macos-domain-explicit-probe-11002 branch 2 times, most recently from 4c166b9 to 60903db Compare September 15, 2026 10:15
@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 Sep 15, 2026
@dwu96
dwu96 force-pushed the fix/service-macos-domain-explicit-probe-11002 branch from 60903db to 1af33d4 Compare September 15, 2026 11:26
@dwu96

dwu96 commented Sep 15, 2026

Copy link
Copy Markdown
Contributor Author

Per-concern dispositions for the two advisory (CONCERNS) verdicts on 60903db0b, addressed at head 1af33d42d:

Design Review, concern 1 (no live launchd ran this revision):

  • Acknowledged as stated in the PR body from the start: the pipeline host is Linux; evidence is the reporter's measured rc pair, two in-repo precedents (pod/launchd.py ships the identical verb with documented rc semantics; Dev Fleet's probe states the same manageable contract), and unit tests. The named clearing condition is a maintainer-side macOS check, which is exactly the ask to whoever merges: run kirocrew service status with the LaunchAgent installed and confirm the summary renders and is_active() flips across install/uninstall.

Design Review, concern 2 (stop() newly reachable with a legacy unload):

First Principles, item 4 (last-exit regex duplicates pod/launchd.py):

  • Adopted, the subtraction as prescribed: the copied regex and the import re are deleted at 1af33d42d; the last-exit read now goes through the module's own _launchctl_print_value for both spellings plus a numeric check, so the placeholder-suppression and both-spellings behaviour is unchanged (all four pinned tests still pass) with zero new parsing machinery. The multiline anchor was not needed: the parser already strips and prefix-matches per line.

First Principles, item 5 (stdout-reason fallback rests on an unverified claim):

  • Declined, with the in-tree evidence the concern asked for: pod/launchd.py's _service_absent scans stdout AND stderr for the not-loaded marker, with a comment explaining that an operational failure and the explicit refusal must be told apart across both streams — the module this PR cites for rc semantics already encodes that launchctl's refusal text is not reliably on stderr. The code comment now cites that precedent instead of asserting the claim bare. The behaviour is strictly additive (stderr text still wins when present; the generic no entry fallback is unchanged and pinned by test in both directions).

First Principles, inventory items 3 and 7 (terse summary and the restart-paragraph doc fix ride along):

  • Item 3 is a reviewed-in requirement, not a ride-along: returning the raw print output would replace a few list lines with a ~3.3 KB dump on the one command an operator runs while diagnosing, and the local Opus lane's rounds hardened it further. Item 7 was adopted from a local Opus round-4 finding: the paragraph documents the exact module this PR corrects launchd facts in, and it was factually false about code this diff touches (restart() shares the new _target()); it is declared in the PR body's disposition record.

@dwu96

dwu96 commented Sep 22, 2026

Copy link
Copy Markdown
Contributor Author

🤖 Kiro Crew [operator: dwu96#8c08bee0]: This PR has been inactive for 7+ days. I reviewed the blockers but they require your input:

  • The only blocking check is the Design Review lane's BLOCK on fe99ea9b8: it will not clear without a live macOS transcript of the three launchd states (running, loaded-not-running, uninstalled) at this revision. Every other lane is green — GPT 5.6 and Opus 4.8 report no blocking findings, First Principles PASSes, and 68 of 70 non-skipped checks pass.
  • That evidence cannot be produced from this pipeline host, which is Linux with no launchd, so the gap is not mechanically resolvable by automation. It needs a decision: run kirocrew service status (or launchctl print gui/<uid>/<label>) on a Mac and paste the transcripts, ask a macOS maintainer to supply them, or request a maintainer override of the Design verdict.
  • A secondary open question the lane raised is in the same class: the PR body concedes a user/<uid> bootstrap configuration where the new domain-explicit probe would miss an agent the old launchctl list saw. Whether that configuration is in scope is a product call, not a code fix.

When you've addressed these, the pipeline will re-assess on its next cycle.

@dwu96 dwu96 added needs-author-decision PR blocked on author input and removed needs-pr-triage PR scanner: awaiting automated triage labels Sep 22, 2026
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Sep 27, 2026

Copy link
Copy Markdown
Contributor

PR triage (2026-10-05): KEEP + REBASE

Checked the full diff against origin/main @ a92dde1a6c (2723 commits past this PR's merge base 0a64f54bf5):

@iamwhatever iamwhatever added the ci:macos Run the on-demand macOS suite against this PR head label Oct 19, 2026
@iamwhatever iamwhatever changed the title fix(service): probe launchd by gui domain target on macOS fix(service): probe launchd by domain target on macOS Oct 19, 2026
@iamwhatever
iamwhatever force-pushed the fix/service-macos-domain-explicit-probe-11002 branch from fe99ea9 to c169eae Compare October 19, 2026 15:28
@iamwhatever
iamwhatever requested review from a team and KiroCrewCaptain as code owners October 19, 2026 15:28
@iamwhatever

Copy link
Copy Markdown
Contributor
  • Unverified platform premise on a core lifecycle path

fixed at c169eae: rebased over #17492; is_active()/status() now probe launchctl print <domain>/<label> over gui/ then user/, the same domains install/stop/restart act on, so the user/ bootstrap gap named in the BLOCK is closed in code, not deferred.
The live-launchd ask is answered by test/test_service_macos_live_launchd.py: darwin-only, it bootstraps throwaway agents into the real gui/ and checks is_active() + status() for running, loaded-never-started, exited 78 and absent (before and after bootout), printing each status() transcript.
This PR now carries ci:macos, so the macOS Tests (on demand) lane runs those against a real launchd at this head; its log is the transcript the BLOCK asks for.

@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 Oct 19, 2026
@github-actions

github-actions Bot commented Oct 19, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

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

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Oct 19, 2026
@iamwhatever iamwhatever removed the ci:macos Run the on-demand macOS suite against this PR head label Oct 19, 2026
@iamwhatever
iamwhatever force-pushed the fix/service-macos-domain-explicit-probe-11002 branch from c169eae to 07be2c5 Compare October 19, 2026 16:53
@iamwhatever

iamwhatever commented Oct 19, 2026 •

Copy link
Copy Markdown
Contributor

self-added: yes
mechanism: live-launchd test module

  • span=90e9d2d412fa Live-launchd cases fail at the host-service guard

fixed at 07be2c5: test/test_service_macos_live_launchd.py is deleted. It bootstrapped real agents, which the root conftest guard and no-test-side-effects forbid outside the opt-in e2e suites.
The probe stays covered by the faked-launchctl tests in test_service_macos_control.py and the stateful stand-in in test_service_macos_launchd_domain.py.

@iamwhatever

iamwhatever commented Oct 19, 2026 •

Copy link
Copy Markdown
Contributor

self-added: yes
mechanism: live-launchd test module

  • span=64a44caa7630 live launchd suite mutates the host's launchd

fixed at 07be2c5: the module is deleted (the reviewer's first option); no test now spawns launchctl bootstrap/bootout for real.

@iamwhatever

iamwhatever commented Oct 19, 2026 •

Copy link
Copy Markdown
Contributor
  • span=87a2a7dd6071 Crash-looping gateway reads as up

fixed at 07be2c5: new macos.is_up() is true only for state = running; controller.service_status() exits on it, as Linux exits on linux.is_up(). A loaded-not-running agent now exits 1; is_active() keeps it reachable to stop.
Pinned by test_service_status_exit_follows_running_not_loaded; cli.md's service status row and the macOS section say so.

@iamwhatever

Copy link
Copy Markdown
Contributor
  • Confirm the macOS Tests (on demand) lane passed on this head

rebutted: the live-launchd module that lane would have run is deleted (host-service guard forbids it), so the lane would only re-run mocked tests that pass on Linux. ci:macos is removed to spare the macOS pool.
Live evidence stays the reporter's measured list rc=1 / print rc=0 pair in #11002; the parsed print fields are those pod/launchd.py already parses on main.

@iamwhatever

Copy link
Copy Markdown
Contributor

Correction to my earlier Design disposition for fe99ea9: the live-launchd test module it cited is deleted at 07be2c5 (the root conftest host-service guard forbids tests that bootstrap real agents outside the opt-in e2e suites), and ci:macos is removed. The probe now covers gui/ and user/, so the user/ gap is closed in code. A real-Mac transcript of kirocrew service status across running / loaded-not-running / uninstalled is still not available from this Linux pipeline; a maintainer with a Mac can supply it, or record a Design override.

is_active() and status() used `launchctl list <label>`, which reads only
the caller's domain and can exit non-zero with empty output for a
serving gui/<uid> agent, so `kirocrew service status` called a running
gateway "not loaded". Both now probe `launchctl print <domain>/<label>`
over gui/<uid> then user/<uid>, the same domains install, stop and
restart address since #17492. status() renders a terse summary (domain,
state, pid, non-zero last exit, plist path). `service status` exits on
a new is_up() (state = running), so a crash-looping agent exits 1 as on
Linux, while is_active() keeps loaded-counts-as-active for reach.

Closes #11002

Co-authored-by: Di Wu <dwu96@users.noreply.github.com>

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

Requesting changes on head b2ed600. Design Review is red with a BLOCK on this head. The CI log says: "Design review verdict for b2ed600: BLOCK".

The design concern: the description says manual verification was not run on a Mac, yet the macOS-only probe now decides the exit code of service status and the result of is_service_active(), which gates server restart. The new tests feed in hand-written launchctl print output, so nothing checks which domain answers launchctl print gui/<uid>/<label> from a desktop session and from SSH, or how the first state = running line looks in real output. If real output differs, Mac users would keep seeing a running gateway reported as down, which is the symptom this PR sets out to fix.

Could you, or a macOS user, run the new probe on a real Mac (desktop session and SSH), paste the real launchctl print output and the service status result into the description, and use that output as a test fixture? Please also update the branch onto main when you push, since these runs are about two weeks old.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 7, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

merge conflict Branch has merge conflicts with its base — author must resolve before merge needs-author-decision PR blocked on author input readiness: action required A blocking check or review needs attention

Projects

None yet

4 participants