fix(install): tolerate absent Windows tasks in stop_supervisor (#4465) (#4468)

## Description

On Windows, a session-scoped fallback install creates only
`<service>-health`, never `<service>-startup`. Re-running `install
apply` then fails in `stop_supervisor`, because `schtasks /End /TN
<service>-startup` runs with `check=True`. `_remove_deployment` has
already deleted the health task by that point but keeps the manifest.
After that, every retry fails at `schtasks /Change /TN <service>-health
/DISABLE` and the profile cannot be recovered.

The fix makes `stop_supervisor` treat a missing task as already stopped.
It uses the same `_require_removal_success(..., absent_text="cannot find
the file specified")` check that `remove_supervisor` uses for `schtasks
/Delete`. Real failures such as access denied still raise. Profiles
already stuck in this state recover on the next `apply` or `remove`,
because both stop and remove now treat missing tasks as success and
`delete_manifest` gets to run.

Closes #4465

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- `headroom/install/supervisors.py`: Windows `stop_supervisor` now runs
the health `/Change /DISABLE` and the startup `/End` through
`run(capture_output=True)` + `_require_removal_success`, treating a
missing task as success. `/End` reports it as "cannot find the file
specified", while `/Change` reports "does not exist in the system"
(found during the real Task Scheduler run below), so
`_require_removal_success` now accepts either message via a shared
`_SCHTASKS_ABSENT_TEXT`.
- `tests/test_install/test_supervisors.py`: a parametrized test checks
that both missing-task messages do not raise, one checks that access
denied still raises `click.ClickException`.
- Not addressed: the "runtime identity changed" message from
`stop_runtime`, which the issue flags as possibly separate.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [ ] Manual testing performed

### Test Output

```text
$ uv run pytest tests/test_install/test_supervisors.py tests/test_cli/test_install_cli.py -q
============================ 138 passed in 19.37s =============================
$ uv run ruff check headroom/install/supervisors.py tests/test_install/test_supervisors.py
All checks passed!
```

## Real Behavior Proof

- Environment: Windows 11 Pro 10.0.26300.9711, Python 3.13.11,
non-elevated shell, real Task Scheduler (no mocks); throwaway
`headroom-proof` service name, so no real profile was touched
- Exact command / steps: (1) `schtasks /Create /TN headroom-proof-health
/TR "cmd /c exit 0" /SC ONCE /ST 23:59 /F` creates a health-only
deployment with no `-startup` task; (2) run a script calling
`stop_supervisor()` with a manifest whose `service_name` is
`headroom-proof`, on `upstream/main` and on this branch; (3) `schtasks
/Delete /TN headroom-proof-health /F`, then run the script again on this
branch (fully absent profile, the state the issue gets stuck in)
- Observed result: upstream/main fails as reported: `ERROR: The system
cannot find the file specified.` / `CalledProcessError(1, ['schtasks',
'/End', '/TN', 'headroom-proof-startup'])`. This branch, health-only:
`SUCCESS: The scheduled task "headroom-proof-health" has been terminated
successfully.` / `STOP OK`. This branch, fully absent: `STOP OK`. The
first revision of this PR failed here with `schtasks health disable
failed: ERROR: The specified task name "headroom-proof-health" does not
exist in the system.`, which led to the second commit. No
`headroom-proof-*` task was left afterwards.
- Not tested: a full `headroom install apply` re-run over a live
session-scoped deployment, end to end

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Minimum rollout channel: n/a
- Stable/default behavior changed: only when a Windows scheduled task is
missing; stop now succeeds instead of failing
- Kill switch / disable path: n/a (CLI install teardown path)
- Unsafe override required: no
- Qualification impact: none
- Rollback path: revert this commit

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
This commit is contained in:
Parideboy
2026-10-28 23:33:38 -05:00
committed by GitHub
co-authored by Claude Opus 5.5 JD Davis
parent abbade9b4c
commit 50af2ff7a8
2 changed files with 90 additions and 5 deletions
+33 -5
View File
@@ -694,6 +694,11 @@ def start_supervisor(manifest: DeploymentManifest) -> None:
subprocess.run(["schtasks", "/Run", "/TN", f"{manifest.service_name}-startup"], check=True)
# `/End` and `/Delete` report a missing task as "cannot find the file specified";
# `/Change` reports it as "does not exist in the system".
_SCHTASKS_ABSENT_TEXT = ("cannot find the file specified", "does not exist in the system")
def stop_supervisor(manifest: DeploymentManifest) -> None:
"""Stop the installed supervisor for a deployment."""
@@ -730,10 +735,32 @@ def stop_supervisor(manifest: DeploymentManifest) -> None:
)
return
if _is_windows():
# Session-scoped fallback installs never create the `-startup` task,
# and the health task may already be absent, so tolerate missing
# tasks (schtasks reports "cannot find the file specified") while
# still surfacing real failures such as access denied.
health = f"{manifest.service_name}-health"
subprocess.run(["schtasks", "/Change", "/TN", health, "/DISABLE"], check=True)
result = run(
["schtasks", "/Change", "/TN", health, "/DISABLE"],
capture_output=True,
text=True,
)
_require_removal_success(
result,
"schtasks health disable",
absent_text=_SCHTASKS_ABSENT_TEXT,
)
subprocess.run(["schtasks", "/End", "/TN", health], check=False)
subprocess.run(["schtasks", "/End", "/TN", f"{manifest.service_name}-startup"], check=True)
result = run(
["schtasks", "/End", "/TN", f"{manifest.service_name}-startup"],
capture_output=True,
text=True,
)
_require_removal_success(
result,
"schtasks startup end",
absent_text=_SCHTASKS_ABSENT_TEXT,
)
def remove_supervisor(manifest: DeploymentManifest) -> None:
@@ -828,7 +855,7 @@ def remove_supervisor(manifest: DeploymentManifest) -> None:
_require_removal_success(
result,
f"schtasks {suffix} delete",
absent_text="cannot find the file specified",
absent_text=_SCHTASKS_ABSENT_TEXT,
)
@@ -843,7 +870,7 @@ def _require_removal_success(
operation: str,
*,
absent_codes: set[int] | None = None,
absent_text: str | None = None,
absent_text: str | tuple[str, ...] | None = None,
) -> None:
returncode = int(getattr(result, "returncode", 0))
detail = _result_text(result)
@@ -851,6 +878,7 @@ def _require_removal_success(
return
if absent_codes and returncode in absent_codes:
return
if absent_text and absent_text in detail.lower():
texts = (absent_text,) if isinstance(absent_text, str) else absent_text or ()
if any(text in detail.lower() for text in texts):
return
raise click.ClickException(f"{operation} failed: {detail}")
+57
View File
@@ -948,6 +948,63 @@ def test_start_and_stop_supervisor_darwin_windows_and_none(monkeypatch) -> None:
]
@pytest.mark.parametrize(
"stderr",
[
"ERROR: The system cannot find the file specified.",
'ERROR: The specified task name "headroom-default-health" does not exist in the system.',
],
)
def test_windows_stop_tolerates_absent_tasks(monkeypatch: pytest.MonkeyPatch, stderr: str) -> None:
# Session-scoped fallback installs never create the `-startup` task, and
# the health task can be missing too, so stop must not raise when
# schtasks reports the task as missing.
monkeypatch.setattr("headroom.install.supervisors.sys.platform", "win32")
calls: list[list[str]] = []
monkeypatch.setattr(
"headroom.install.supervisors.subprocess.run",
lambda command, **kwargs: _LaunchctlResult(0),
)
def fake_run(command: list[str], **kwargs: object) -> object:
calls.append(command)
return type(
"Result",
(),
{
"returncode": 1,
"stdout": "",
"stderr": stderr,
},
)()
monkeypatch.setattr("headroom.install.supervisors.run", fake_run)
stop_supervisor(_manifest(supervisor=SupervisorKind.SERVICE.value))
assert calls == [
["schtasks", "/Change", "/TN", "headroom-default-health", "/DISABLE"],
["schtasks", "/End", "/TN", "headroom-default-startup"],
]
def test_windows_stop_surfaces_access_denied(monkeypatch: pytest.MonkeyPatch) -> None:
monkeypatch.setattr("headroom.install.supervisors.sys.platform", "win32")
def fake_run(command: list[str], **kwargs: object) -> object:
return type(
"Result",
(),
{
"returncode": 1,
"stdout": "",
"stderr": "ERROR: Access is denied.",
},
)()
monkeypatch.setattr("headroom.install.supervisors.run", fake_run)
with pytest.raises(click.ClickException, match="Access is denied"):
stop_supervisor(_manifest(supervisor=SupervisorKind.SERVICE.value))
def test_macos_start_bootstraps_when_job_not_registered(monkeypatch, tmp_path: Path) -> None:
# Post-`stop`/`restart` state: the job was booted out, so `kickstart` fails
# (launchctl 113) and start must bootstrap the plist instead.