PR #59335: fix(daemon): preserve Windows Task Scheduler settings on reinstall and exit early on failed restart

• Repository: openclaw/openclaw
• Author: tmimmanuel
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/59335

Description (problem / solution / changelog)

Summary

• Problem: openclaw gateway install uses schtasks /Create /F which resets user-configured Task Scheduler settings (run level, logon type, privileges) on every reinstall. openclaw gateway restart hangs ~60s when the gateway fails to start.
• Why it matters: Windows users who configure elevated privileges via Task Scheduler UI lose their settings on every install/upgrade. The restart hang makes the CLI appear frozen.
• What changed: activateScheduledTask now uses schtasks /Change /TR when the task already exists, preserving all other settings. waitForGatewayHealthyRestart exits early after ~3s when the task is clearly stopped and the port is free.
• What did NOT change (scope boundary): New task creation still uses /Create /F. Restart health check timeout, retry logic, and stale PID handling are unchanged.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #59271
• This PR fixes a bug or regression

Root Cause / Regression History (if applicable)

• Root cause: activateScheduledTask unconditionally uses schtasks /Create /F which overwrites all task properties. The post-restart health loop has no early exit for a clearly-dead gateway.
• Missing detection / guardrail: No test asserted that existing task settings survive a reinstall. No early exit condition in the health loop for stopped+free state.
• Prior context: The /Create /F pattern has been present since the original schtasks implementation. The health loop timeout (60s) was designed for slow VM startups but has no fast-fail path.
• Why this regressed now: Not a regression per se — the settings-reset was always present but became more visible as users customized task privileges. The restart hang became noticeable after hardened stop/cleanup logic (commit 5ea03efe92) added more sequential waits.
• If unknown, what was ruled out: N/A

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/daemon/schtasks.install.test.ts
• Scenario the test should lock in: When task already exists (mock returns code 0), install uses /Change not /Create /F.
• Why this is the smallest reliable guardrail: Verifies the schtasks command sequence without requiring a real Windows Task Scheduler.
• Existing test that already covers this (if any): Updated existing writes quoted set assignments and escapes metacharacters test to assert /Change path.
• If no new test is added, why not: Existing test was updated. Early exit in health loop is covered by existing restart-health.test.ts passing (no false early exits).

User-visible / Behavior Changes

• openclaw gateway install --force no longer resets Task Scheduler run level, logon type, or privileges on existing tasks.
• openclaw gateway restart exits in ~3s instead of ~60s when the gateway fails to start.

Diagram (if applicable)

Before (install):
[gateway install] -> [schtasks /Create /F] -> all task settings reset

After (install):
[gateway install] -> [task exists?] --yes--> [schtasks /Change /TR] -> settings preserved
                                    --no---> [schtasks /Create /F]  -> new task created

Before (restart):
[gateway restart] -> [task stopped + port free] -> wait 60s -> timeout error

After (restart):
[gateway restart] -> [task stopped + port free x6] -> bail after ~3s -> timeout error

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No (same schtasks binary, different subcommand)
• Data access scope changed? No

Repro + Verification

Environment

• OS: Windows 11 Home
• Runtime/container: Node.js 24.x, npm global install
• Model/provider: any
• Integration/channel: N/A
• Relevant config: default gateway config with Windows Scheduled Task

Steps

1. openclaw gateway install — task created
2. Open Task Scheduler UI, change task to "Run whether user is logged on or not" with elevated privileges
3. openclaw gateway install --force

Expected

• Task settings (logon type, run level) preserved after step 3

Actual (before fix)

• Task settings reset to defaults (Run only when logged on, LIMITED)

Evidence

• Failing test/log before + passing after
  • schtasks.install.test.ts updated to verify /Change path; all 43 tests pass across schtasks.install, schtasks.stop, restart-health, and lifecycle suites.

Human Verification (required)

• Verified scenarios: All related test suites pass (43 tests). TypeScript type-check passes with no errors in changed files.
• Edge cases checked: /Change failure falls back to /Create /F. Health loop early exit requires 6 consecutive stopped+free checks (not a single flap).
• What you did not verify: Manual testing on Windows (no Windows environment available). Real schtasks behavior with /Change /TR.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No

Risks and Mitigations

• Risk: schtasks /Change may behave differently across Windows editions (Home vs Pro vs Server) or locales.
  • Mitigation: Falls back to /Create /F if /Change fails, preserving original behavior.
• Risk: Early exit in health loop could bail prematurely if task status briefly reports "stopped" during startup.
  • Mitigation: Requires 6 consecutive stopped+free checks (~3s), giving the task scheduler time to transition.

Changed files

• src/channels/plugins/contracts/channel-import-guardrails.test.ts (modified, +2/-0)
• src/cli/daemon-cli/restart-health.ts (modified, +27/-0)
• src/daemon/schtasks.install.test.ts (modified, +50/-3)
• src/daemon/schtasks.startup-fallback.test.ts (modified, +2/-0)
• src/daemon/schtasks.ts (modified, +37/-0)