[houlianpi]

Requirement

Closes #34

User-visible result

Windows app_launch now returns stable fixed error, error_code, stage, and retryable fields for process-start, elevation, discovery, ambiguity, readiness, binding, connection-loss, snapshot, and unknown failures. Existing successful launch/snapshot responses and tool schemas remain unchanged.

Scope

• Add an enum-only internal launch failure and state-based classification.
• Serialize fixed safe descriptions and preserve only validated descriptions through the result sanitizer.
• Document the staged response contract and the existing 1–120 second launch timeout (default 15).

Non-goals

• No new MCP tool.
• No snapshot/launch split.
• No transport recovery or raw diagnostic output.

Interface changes

app_launch error responses retain status, error, and data, and add error_code, stage, and retryable. data is empty on launch/snapshot failure.

Acceptance scenarios

• Known launch-stage failures return fixed machine-readable classifications through MCP.
• Unknown exceptions fail closed as nonretryable INTERNAL_ERROR at internal.
• Responses and logs exclude path, title, argument, exception, traceback, secret, UI-value, and partial-snapshot canaries.

Verification evidence

Check	Result	Evidence
Targeted staged-error tests	Pass	22 passed (tests/test_launch_errors.py)
Windows MCP package suite	Pass	103 passed, 2 skipped
Clean built-wheel MCP smoke	Pass	Missing executable → PROCESS_START_FAILED; real no-window process → retryable WINDOW_NOT_FOUND; delayed-title Tk app with 4-second timeout → success; executed from a clean business project with installed wheels and MCP 1.29.1
Independent code review	Approved	Commit 2a005cf; no blocking correctness, compatibility, or security findings
Independent security review	Approved	No blocking findings; fixed allowlist, structural WinError 740 handling, fail-closed unknowns, and partial snapshot clearing reviewed

Agent roles

• Implementer: current coding session
• Reviewer: independent Issue34CodeReview session
• Security reviewer: independent Issue34SecurityReview session
• Acceptor: pending clean black-box acceptance session

Security impact

• Exception bodies, executable paths, titles, arguments, tracebacks, secret values, and UI content are not projected into failure responses or logs.
• Unknown exceptions use a fixed nonretryable internal classification.
• The generic sanitizer restores an error description only when code, stage, retryability, and description exactly match the fixed allowlist.
• Snapshot failure clears partial response data.

Compatibility impact

Successful app_launch payloads and all 22 tool input schemas are unchanged. Error payloads become more specific while retaining the existing top-level fields. launch_timeout_seconds remains optional, bounded to 1–120, and defaults to 15.

Rollback

Revert commit 2a005cf; callers return to the generic Operation failed launch response.

Known limitations

Hosted CI cannot prove interactive desktop readiness. The clean local Windows smoke exercised real process-start failure, discovery timeout, and delayed-title success; deterministic tests cover every code and state transition. Elevation, ambiguity, visibility, enabled-state, binding, connection-loss, and snapshot classes remain subject to independent black-box acceptance using the established native matrix.

[houlianpi]

Final evidence for head 72f1d6f1331573edb24b945e64dde42f09e8377d:

• Package tests: 103 passed, 2 skipped after resolving against merged PR fix(windows): promote deterministic launch deadline to main #41.
• Quality Gates: success.
• Windows runtime package: success.
• Independent code review: APPROVE; staged errors and deadline behavior preserved, no duplicate/dropped definitions.
• Independent security review: APPROVE; fixed projection, exact sanitizer allowlist, fail-closed unknowns, payload-free diagnostics, and partial snapshot clearing preserved.
• Independent clean black-box acceptance: ACCEPT from a fresh LF-preserving detached checkout and fresh built wheels with MCP 1.29.1. Actual stdio MCP observed PROCESS_START_FAILED/process_start/false, WINDOW_NOT_FOUND/window_discovery/true, delayed-title launch success, and close success. Synthetic path/title/argument/secret/UI canaries were absent from responses and diagnostics; cleanup left zero controlled processes.

Roles remained separate: implementer, code reviewer, security reviewer, and acceptor used separate sessions.