Expose bounded AppInstallManager status and completion monitoring

Parent: #232

Dependencies and access restriction

Depends on the merged #234 and #236 foundations for the approved initial subset below. The maintainer approved that scoped implementation on 2026-09-15 after a separately authorized passive manager-event probe. #233 remains open for authoritative support clarification but is not a blanket development blocker for this subset. Other event surfaces, broader scopes and group guarantees remain gated; the release hold remains unchanged.

Microsoft documents AppInstallManager access as protected by a private capability restricted to Microsoft-developed apps. Do not bypass that restriction or treat runFullTrust/admin access alone as sufficient.

Approved initial implementation scope — 2026-09-15

• Caller-only monitoring with an explicit context and one exact context-local item selection.
• Use the manager ItemStatusChanged/ItemCompleted events already exercised by the passive probe as bounded invalidation signals. Do not expose unverified per-item events, follow the whole queue, substitute another item by product/package strings, or add other-user scope.
• Bound waiting and buffering, capture/output on the cmdlet execution path, preserve exact identity/lifetime ownership, and clean up on every exit. Local cancellation stops observation only, never installation.
• Do not infer group/queue completion, terminal success from a notification alone, or lossless native ordering. Resolve exact-item leases and context-close coordination with deterministic coverage.
• Development uses fake adapters only. Any additional live metadata, subscription, item/status read or other AppInstall operation requires separate explicit approval.
• Update the compiled command, exports, help, tests and unreleased notes in a separate PR. No version bump or release; AppInstall stays unreleased until support is clarified.

Broader family coverage below remains backlog scope, not implicit authorization.

API scope

Manager ItemStatusChanged/ItemCompleted and associated item StatusChanged/Completed events, with current-status snapshots.

Acceptance criteria

• Provide a compiled monitoring surface with an explicit bounded wait/timeout and typed identity-bearing events or snapshots.
• Close the subscribe-versus-initial-snapshot race; define ordering, duplicate/coalescing behavior, queue/group completion and handling of already-terminal or disappeared items.
• Marshal callbacks safely onto the cmdlet's execution path; never call WriteObject, WriteError or progress APIs directly from arbitrary WinRT callback threads.
• Preserve terminal errors, HRESULTs and cancellation. Stopping observation, timeout or Ctrl+C does not silently cancel an installation.
• Unsubscribe every event and release owned resources on normal completion, timeout, cancellation, pipeline stop and error; bound queued notifications.
• Separate progress output from success-stream objects, and distinguish terminal success from merely receiving a completion notification.

Shared delivery requirements

Follow the parent epic's compiled-C# contract, user-scope and capability/version gates. Include deterministic Pester 6.2+ coverage, comment-based help, public documentation and unreleased notes in the same implementation PR. Use fail-closed fake adapters for side effects; no real installs, entitlement grants or settings changes in CI. Preserve original errors and distinguish unavailable, unknown, requested and completed outcomes.

Documented API references

• https://learn.microsoft.com/uwp/api/windows.applicationmodel.store.preview.installcontrol.appinstallmanager.itemstatuschanged
• https://learn.microsoft.com/uwp/api/windows.applicationmodel.store.preview.installcontrol.appinstallmanager.itemcompleted
• https://learn.microsoft.com/uwp/api/windows.applicationmodel.store.preview.installcontrol.appinstallitem.statuschanged
• https://learn.microsoft.com/uwp/api/windows.applicationmodel.store.preview.installcontrol.appinstallitem.completed
• https://learn.microsoft.com/uwp/api/windows.applicationmodel.store.preview.installcontrol.appinstallstatus

Delivery status — 2026-09-16

The approved exact-item, caller-scoped subset is merged in #253 (c7d03fc6ffd5fffcd9e3dd6724037947847309bc). Wait-AppInstallItem requires an explicit context, one retained local item ID and a 1–30 second timeout. Manager events are bounded invalidation signals; snapshots are captured on the command execution path, with at most 64 retained observations and one result emitted after cleanup. Local cancellation stops observation only.

This issue remains open for broader family coverage. Per-item event subscriptions, whole-queue following, multiple-target/group waits, other-user variants and stronger native lifetime/ordering guarantees remain gated. Any further live metadata, subscription or item/status probe requires fresh approval. #233 is unresolved and AppInstall remains unreleased; no module version or tag was published for this implementation.

Start with the merged implementation in #253 and the Wait-AppInstallItem entry point, then review the parent epic and the documented AppInstallManager references. The remaining family, group, other-user, and stronger lifetime/ordering coverage is gated; done requires explicit approval, deterministic Pester 6.2+ coverage, cleanup, documentation, and unreleased notes.