[m-enes-senovali]

A forced WPPConnect reinstall can restore an older WA catalogue while the six-hour refresh timestamp still suppresses a check. A permanent VoIP WASM contract failure can then spend the readiness budget retrying initialization.

This change ties refresh state to the installed catalogue and API tree, preserves a newer compatible catalogue across npm setup, and shares a bounded VoIP initialization policy between warmup and call readiness.

• Resolve the catalogue where WPPConnect actually loads it (nested before hoisted), validating dependencies at the destination. Preserve the snapshot's own newer dependencies.
• Use one post-npm apply/freshness path for initial, modules-only, forced, staged, and CLI setup. Preserve a compatible local snapshot even when cancellation arrives just after npm; require a usable catalogue before reporting setup success.
• Coordinate setup, catalogue publication, API swap and rollback with a gate outside the API tree. Download outside that gate and recheck installation identity before publication/state writes.
• Share in-flight VoIP initialization and permit at most one retry per page. Fail early only for a known permanent failure with failed=true and canRetry=false; keep bounded waits for unknown/pending states.
• Add synthetic regression coverage, Windows long-path handling, and changelog/help updates in all seven locales.

Validation (overlapping groups; do not sum as one suite):

• Focused refresh/setup/staging/policy/controller/patch-boundary group: 239 passed, 153 skipped, 8 deselected. Generated-API comparisons skip in a checkout without the vendored tree.
• Cancellation/rename/glue: 11 passed; policy/controller harness, guide coverage and desktop AST guards: 1801 passed.
• Three source-review regression cases passed; affected setup/apply/snapshot/dependency group: 47 passed, 93 deselected.
• Changed Python parsed; all three changed TypeScript files passed Node syntax checks; diff checks passed. No local full suite or GUI tests were run.
• Local winzapp-reviewer approved the 47-file implementation after three findings were fixed, and separately approved the subsequent changes to three existing test files. This is local source approval, not a GitHub APPROVED review.

CI follow-up: the first run exposed twelve failures in existing setup tests: eight source-inspection guards still inspected the entry wrappers after their bodies moved into catalogue-gated helpers, and four fake-npm success cases did not create a catalogue. The guards now inspect the called implementation bodies, retaining their assertions. The fake npm now creates a tiny valid catalogue with offline registry I/O, while a new negative case proves that npm success without a catalogue is rejected. The affected groups passed locally (16 and 34 tests); runtime files were unchanged. The final PR contains 50 changed files. Final-head CI is tracked separately from the earlier failed/superseded runs.

Limits: registry checking uses /latest; incompatible latest, offline, integrity or dependency failures remain explicitly unconfirmed. This does not search historical versions, change the homologated runtime/document pins, reload a live page, restart Node, or resend a call. In-place npm setup is not made fully atomic. The reported live incident and its installed package origin were not reproduced; no installed app, account, device or live call was accessed. CI and maintainer review remain required before release.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[gustavo-barrios2006]

Excellent improvement, Muhammet.

Thank you very much for your great contribution.