launchctl bootout --wait is a usage error on macOS 15, so boot-service install/update/restart fails

[keithce]

Summary

On macOS 15, launchctl bootout --wait <service-target> is a usage error, so the boot service's stop step never runs. The old job keeps the label, and the strict bootstrap that follows fails with EIO. The result is that t3 service install, t3 update, and the post-update restart all fail on this OS, leaving the previous server running.

Environment

• macOS 15.7.9 (build 24G830), Darwin 24.6.0
• Darwin Bootstrapper Version 7.0.0
• t3 0.0.41-nightly.20260915.1752

Reproduction

$ launchctl bootout --wait gui/501/com.t3tools.t3code.service
Unrecognized target specifier.
Usage: launchctl bootout <domain-target> [service-path1, service-path2, ...] | <service-target>
<service-target> takes a form of <domain-target>/<service-id>.
Please refer to `man launchctl` for explanation of the <domain-target> specifiers.
$ echo $?
64

$ launchctl bootout gui/501/com.t3tools.t3code.service
$ echo $?
0

With a service already installed, t3 update <version> --yes then reports:

CliUpdateError: t3@<version> is installed but the background service could not be
updated: Background setup failed while starting the service (exit code 5).

and ~/.t3/userdata/logs/boot-service.log shows the two steps in order:

Background setup failed while stopping the installed launch agent (exit code 64).
Background setup failed while starting the service (exit code 5).
Background setup failed while restarting the service after a failed update (exit code 5).

Cause

launchdManager in apps/server/src/cloud/bootService.ts passes --wait to bootout in both its stop and deactivate steps:

args: ["bootout", "--wait", serviceTarget],

The accompanying comment reads "--wait (present on modern macOS, absent from the man page)". It is not present on macOS 15: launchctl rejects the whole invocation as a usage error rather than ignoring the flag. Because the step is optional: true, the failure is logged and the flow continues to bootstrap, which is exactly the EIO case the flag was added to avoid.

Suggested fix

Try the flag, fall back to a plain bootout, and wait for the label to leave the domain either way, so both old and new launchctl behave:

launchctl bootout --wait "$target" 2>/dev/null || launchctl bootout "$target" 2>/dev/null
i=0
while launchctl print "$target" >/dev/null 2>&1 && [ "$i" -lt 90 ]; do sleep 1; i=$((i + 1)); done

I am running that locally as a patch and t3 update now installs and restarts the service cleanly, including a downgrade back to the previous version. Happy to send it as a PR if you would like it in this shape.

[juliusmarminge]

Confirmed on current main. This is a real bug, not a duplicate of #11054 / #11055.

launchdManager still stops and deactivates with an undocumented flag:

args: ["bootout", "--wait", serviceTarget],

https://github.com/pingdotgg/t3code/blob/main/apps/server/src/cloud/bootService.ts#L330-L339
https://github.com/pingdotgg/t3code/blob/main/apps/server/src/cloud/bootService.ts#L369-L376

The comment says --wait is “present on modern macOS, absent from the man page.” On macOS 15.7.9 (Darwin 24.6.0) it is a usage error: launchctl treats --wait as a target specifier and exits 64. The man page still documents only bootout <domain-target> […] | <service-target>.

Because that step is optional: true, runSteps logs the 64 and continues (bootService.ts around the optional-ignore path). install / restart then run strict bootstrap, which fails EIO (exit 5) while the old job still holds the label. The failed-update recovery path bootstraps again and fails the same way. That is exactly the boot-service.log sequence in the report, and it is what t3 update --yes wraps as:

CliUpdateError: … the background service could not be updated: Background setup failed while starting the service (exit code 5).

(apps/server/src/cli/update.ts maps BootServiceCommandError into CliUpdateError after install({ start: true }).)

By then the unit/state files may already name the new version, so the machine can be half-updated: new plist on disk, old server still running.

Scope

• Broken when a job is already loaded: t3 service install (repair), t3 update … --yes, t3 service restart.
• First install (no loaded job) should still work: stop is skipped or the ignored 64 is followed by a successful bootstrap.
• t3 service uninstall can “succeed” while leaving the job running, because deactivate uses the same optional bootout --wait.
• Tests currently assert the broken argv (bootService.test.ts).

Prior art: #7874 (fix(server): wait for launchd shutdown safely) already dropped --wait, treated only confirmed not-loaded stderr as success, and polled launchctl print until the exact label left gui/<uid> (120s bound). It was closed in the open-PR sweep as “launchctl bootout --wait already on main” — that flag is the defect, not the fix. No open PR replaces it.

Fix direction (do not open a competing PR — @keithce offered one and has a working local patch):

1. Stop passing --wait as a required argument. If you probe it at all, fall back immediately on usage/64.
2. launchctl bootout <service-target>, then poll launchctl print <service-target> until the label is gone or the existing 120s stop timeout elapses.
3. Fail closed on unexpected bootout/print errors; keep already-absent idempotent only for launchd’s not-loaded / no-such-process responses.
4. Update the tests that hard-code bootout --wait.

Workaround until a fix ships (as root of the logged-in GUI user):

label="gui/$(id -u)/com.t3tools.t3code.service"
launchctl bootout "$label"
i=0
while launchctl print "$label" >/dev/null 2>&1 && [ "$i" -lt 90 ]; do sleep 1; i=$((i + 1)); done

Then retry t3 service install or t3 update <version> --yes.

[keithce]

PR opened: #12005 replaces the unsupported bootout --wait call with plain bootout plus bounded launchctl print verification, with focused regression coverage.