[lidge-jun]

Summary

Slice 3 of 3 for #7771 Option B (owner-approved design in devlog/_plan/261111_windows_service_stop/): the Desktop side. It is safe to merge before the CLI slices, because it only passes information a CLI that does not know it ignores, and only reads fields an older CLI leaves out.

• Deadline hand-off: both Desktop ocx stop children (the consented takeover at startup and the exit/restart drain) now receive OCX_STOP_DEADLINE_MS, measured just before the spawn: the remaining startup deadline minus 5 s for the takeover (the silence probe and claim::run still run under that deadline), the drain deadline minus 3 s for the drain. When nothing positive is left the variable is set to an empty value, which means "no deadline", so a value inherited from Desktop's own environment can never reach the child. The design names a --deadline-ms flag; the CLI slice accepts both, and Desktop uses only the environment variable because an older CLI rejects an unknown flag.
• Windows exit drain: runtime_stop::DEADLINE is 75 s on Windows (72 s handed to the CLI) and stays 30 s elsewhere, so a checked Windows stop that waits for the port fits (030's budget: 56 s worst case + pre-admission allowance + two inherited receipts = 70 s).
• New ocx-stop/1 fields: StopSummary reads the additive serviceStopReason (access-denied, evidence-unreadable, unbound-wrapper, unverified-budget; unknown strings kept) and portHeldByForeign (absent or null = false), both serde(default), no deny_unknown_fields, no new Outcome/Proxy value. They add one plain sentence to the stop description (elevated terminal, retry from a terminal, a wrapper started outside the service, unreadable process state, another program holds the port) and never change the verdict.
• Docs: structure/ops/desktop-supervision.md (hand-off, 75 s, fields), structure/desktop-shell.md (named the drain deadline correctly), and 030/050 of the design now say Desktop uses the environment variable.

Refs #7771.

Verification

• Fail-first: six new Rust tests (old documents unchanged, each known reason, unknown reason tolerated, portHeldByForeign true/false/null, hand-off values incl. the omitted and sub-millisecond edges, 75 s vs 30 s) failed to compile on the unchanged code (missing helpers and fields) and pass now.
• cargo test --lib for desktop/src-tauri: 309 passed, 0 failed, 2 ignored. cargo clippy --all-targets -- -D warnings and cargo fmt --check: clean. Local macOS build needed a scratch shim for the Swift NativeTray step (Command Line Tools without Xcode) and the CI "prepare desktop check resources" placeholders; no test touches the tray.
• bun run privacy:scan, bun run structure:check: pass.

NOT RUN:

• cargo check --target x86_64-pc-windows-msvc (needs Windows SDK headers); the Windows value is covered through drain_deadline_for(true).
• Windows real device; a real Desktop to CLI run (the CLI slices are not merged yet).

Checklist

• Scope stays focused and avoids unrelated cleanup.
• Docs or release notes were updated when needed.
• Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults.

Summary by CodeRabbit

• Bug Fixes
  • Desktop shutdown and restart operations on Windows can now take up to 75 seconds to complete, reducing the chance that a runtime stop is cut short. Other platforms retain a 30-second limit.
  • Stop status messages now include available service-stop reasons and indicate when another process is using the port.
• Documentation
  • Updated guidance to reflect platform-specific stop limits and the additional details that may appear in stop messages.

[chatgpt-codex-connector]

Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-11-11T16:04:59.930937Z	1f289a0	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[github-actions]

✅ Deterministic PR hygiene checks passed.

[coderabbitai]

Caution

Review failed

The pull request is closed.

Walkthrough

Desktop stop handling now passes a caller deadline to stop processes through OCX_STOP_DEADLINE_MS, with platform-specific drain limits and reserved margins. Stop results also include optional service-stop and foreign-port details in their descriptions. Documentation and tests cover these changes.

Changes: Desktop stop handling

Layer / File(s)	Summary
Deadline calculation and propagation desktop/src-tauri/src/runtime_stop.rs, devlog/_plan/261111_windows_service_stop/030_design.md, devlog/_plan/261111_windows_service_stop/050_rollout_risks.md, structure/desktop-shell.md, structure/ops/desktop-supervision.md	The drain limit is 75 seconds on Windows and 30 seconds elsewhere. Stop processes receive the positive remaining deadline in OCX_STOP_DEADLINE_MS, after a 3-second drain margin or 5-second takeover margin. Tests cover the calculations and limits; documentation records the deadline behavior.
Stop summary details and descriptions desktop/src-tauri/src/runtime_stop.rs, structure/ops/desktop-supervision.md	StopSummary accepts optional service-stop and foreign-port fields. Descriptions include notes for recognized or unknown service-stop reasons and for a foreign port when its value is true. Tests verify descriptions, compatibility with older documents, and unchanged result classifications.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Feature

Possibly related issues

• [Bug][Windows]: desktop 2.92.0 stuck at taking-over when an npm package runtime runs under the Task Scheduler service; ocx stop / service stop do not free the port #7771: The issue describes the stop-flow conditions addressed by the deadline propagation and additional service-stop and port details, though this PR does not establish that it resolves the reported runtime-owner problem.
• Restart and disconnect for a client runtime whose owner cannot be proven (legacy bare-flag service children and companion proxies) #8545: The issue concerns stop behavior when runtime ownership is uncertain; this PR changes the Windows stop drain and exposes service-stop and port-ownership details, but does not implement the ownership-proof design.

Possibly related PRs

• lidge-jun/opencodex#8546: It defines the Windows stop design whose caller-deadline and stop-result details this PR passes through and consumes at the Desktop boundary.

Suggested labels: enhancement

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

• X
• Mastodon
• Reddit
• LinkedIn

[lidge-jun]

Maintainer judgment (#7771 Option B, slice 3: Desktop)

• Value: lets Desktop's two ocx stop children (the consented takeover and the quit/restart drain) learn their real deadline. It also gives a checked Windows stop that waits for the port enough time (75 s on Windows), and surfaces the new stop reasons. This is the Desktop half of the design the owner approved.
• UX change: the quit/restart drain on Windows may now wait up to 75 s instead of 30 s before reporting failure; other platforms keep 30 s. Stop failures can now carry one plain extra sentence (elevated terminal, retry from a terminal, a wrapper outside the service, another program on the port). No verdict changes.
• Regression evidence: safe before the CLI slices, because the current CLI ignores the variable and leaves out the fields. Older documents parse unchanged, and null or unknown values are tolerated. Desktop Rust suite: 309 passed, 0 failed (reviewer reproduced it).
• Windows impact: the Windows deadline is chosen through drain_deadline_for(true) and tested on macOS. A failed drain still quits (app.exit(0)) or refuses a restart, so nothing hangs past the deadline. Windows build and real device: NOT RUN.
• Verification scope: fresh independent review APPROVE and SECURITY APPROVE on 1f289a0362 (no elevation, no new kill authority, Desktop: state the acceptance conditions for taking over an existing package runtime and for reusing consent #5443 boundary unchanged).
• Follow-ups carried into the CLI slice (non-blocking doc points from the review): 030 and structure/ops/desktop-supervision.md will say an empty OCX_STOP_DEADLINE_MS is treated as absent. 030's Desktop paragraph will state 75 s on Windows. The CLI counts the deadline from its own process start.
• NOT RUN: cargo check for Windows (needs the Windows SDK), a real Desktop-to-CLI run, full bun run test (no TypeScript change).