mustflow 2.116.0 → 2.116.2

package/templates/default/locales/en/.mustflow/skills/modal-loop-reentrancy-review/SKILL.md

@@ -0,0 +1,294 @@
+---
+mustflow_doc: skill.modal-loop-reentrancy-review
+locale: en
+canonical: true
+revision: 2
+lifecycle: mustflow-owned
+authority: procedure
+name: modal-loop-reentrancy-review
+description: Apply this skill when desktop or embedded UI code creates, changes, reviews, debugs, or reports modal dialogs, nested event loops, message pumping, synchronous UI waits, run-loop modes, dispatcher frames, local event loops, dialog exec APIs, synchronous cross-thread messages or RPC, file-picker portals, tracking loops, or callbacks that can reenter code before the outer handler returns and cause deadlock, livelock, starvation, stale-state mutation, or owner-lifecycle corruption.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.modal-loop-reentrancy-review
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - test_audit
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Modal Loop Reentrancy Review
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Review modal and nested event-loop behavior as synchronous call-stack reentrancy, not as an
+application pause.
+
+A modal loop can keep an outer handler, lock, iterator, routed event, COM or IPC callback, and
+partially updated model alive on the stack while dispatching another event inside it. The review
+question is whether any reentered path can observe invalid intermediate state, wait on the outer
+frame, starve the only exit source, or resume the outer frame against a changed owner.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- Code uses blocking dialog, modal window, nested dispatcher frame, local event loop, manual
+  `processEvents`, message pump, synchronous file picker, menu or drag tracking loop, COM or RPC
+  call that pumps messages, or cross-thread synchronous UI messaging.
+- UI code waits synchronously for a task, future, worker, dispatcher callback, portal response,
+  network result, lock, event, thread, or another UI thread.
+- A callback opens UI before returning to WebView, browser, accessibility, IPC, D-Bus, framework,
+  plugin, or native host code that may serialize or prohibit reentrancy.
+- A bug reports frozen dialog, responsive-but-never-finishing UI, nested confirmations, stale event
+  continuation, callback starvation, wrong owner disable, lost capture, late completion, or
+  platform-specific modal behavior.
+- Code or docs claim a modal dialog pauses the app, a recursive lock fixes reentrancy, pumping events
+  makes a wait safe, or one framework's nested-loop behavior applies to every platform.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task is dialog semantics, focus order, Escape behavior, accessible naming, or keyboard
+  navigation without nested-loop or reentrancy risk; use `frontend-accessibility-tree-review`.
+- The task is only animation interruption or nonblocking overlay motion; use
+  `motion-system-contract-review`.
+- The main problem is parallel shared-memory execution with no nested dispatch on one call stack;
+  use `race-condition-review` or `concurrency-invariant-review`.
+- The main problem is fixed sleeps, readiness polling, or ordinary asynchronous timing without
+  nested pumping; use `async-timing-boundary-review`.
+- The deadlock is primarily database locks or transaction isolation; use the database lock or
+  transaction integrity skill.
+- The task merely styles a CSS modal or renders a dialog component whose result is already
+  nonblocking and lifecycle-safe.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Entry ledger: outer handler or callback, call stack, UI thread, owner, request, modal depth,
+  current state and locks, nested-loop API, and exact return or exit condition.
+- Dispatch ledger: queued and synchronous messages, callbacks, timers, sockets, I/O sources,
+  accessibility or IPC sources, run-loop mode or main context, dispatcher priority, filters, and
+  source thread or affinity.
+- Wait-for ledger: threads, tasks, locks, events, synchronous messages, RPC or COM calls, dispatcher
+  operations, portal requests, completion callbacks, and the context required to run each one.
+- Reentrancy invariant: fields that must change together, transient state exposed across the nested
+  loop, stale iterators or object references, allowed nested callbacks, and forbidden reentry.
+- Request lifecycle: stable request and owner IDs, state machine, generation, cancellation,
+  single-flight or queue policy, exactly-once result, late-completion behavior, and owner disposal.
+- Modal session ledger: session-specific loop and exit token, nested depth and parent session,
+  completion and commit authority, owner-disable and capture ownership, input generation, hidden
+  versus closed state, deferred destruction, weak owner reference, and idempotent cleanup owner.
+- Platform ledger: framework and version, backend, native versus portal dialog, process boundary,
+  apartment or thread-affinity model, event-loop modes, and current official or repository-owned
+  behavior evidence.
+- Diagnostic and test evidence: modal spans, loop depth, call and wait graphs, source priority and
+  context, low-overhead event ring, stacks, CPU state, system trace correlation, deterministic
+  reentry fixtures, and configured command intents.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- The task matches the Use When conditions and does not match the exclusions.
+- Higher-priority instructions and `.mustflow/config/commands.toml` have been checked.
+- The actual nested-loop or synchronous wait boundary is identified before changing dialog code.
+- Platform behavior is matched to the repository's framework, backend, apartment and version.
+  External examples are evidence only and are not copied as universal rules.
+- Existing async dialog, request state-machine, owner lifecycle, cancellation, dispatcher,
+  instrumentation and test patterns have been searched.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Replace blocking result APIs with future, task, callback or signal result APIs.
+- Post presentation until the current callback has returned; add request state machines, owner-scoped
+  single-flight or queue policy, stable IDs and revisions, exactly-once completion, cancellation,
+  late-result guards, narrow window or document scope, and focused fixtures.
+- Move locks, mutable iterators, partial model changes, synchronous I/O, remote validation, and
+  long-running work outside nested dispatch windows.
+- Add modal-depth spans, dispatcher or source lifecycle records, wait-for edges, low-overhead event
+  rings, state hashes, and watchdog evidence collection.
+- Add pre-pump admission guards, atomic pre-modal snapshots, session-scoped `TryComplete`, one
+  commit observer, weak-reference plus generation checks, nested owner-disable accounting,
+  session-specific exit tokens, stale-input invalidation, and idempotent finalization.
+- Prefer inline confirmation, undo, soft delete, staged apply, sheets, or nonblocking overlays when
+  they preserve the product contract.
+- Do not replace a nonrecursive lock with a recursive lock as proof of safety.
+- Do not add manual event pumping, busy `processEvents` loops, sleeps, or global reentrancy booleans
+  as generic fixes.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Find every nested dispatch and sync-over-async boundary.
+   - Search blocking dialog and file-picker calls, local loop execution, dispatcher frames, message
+     pumping, synchronous cross-thread messaging, task or future waits, joins, RPC, COM calls, and
+     callbacks that open UI before returning.
+   - Include menu, drag, resize and event-tracking loops even when no dialog is visible.
+2. Capture the outer frame that stays alive.
+   - Record handler, event, owner, request, locks, iterators, mutable references, partial state,
+     transaction or callback contract, and code that resumes after the nested loop exits.
+   - State the invariant reentered code is forbidden to observe.
+3. Close lock and partial-state windows before pumping.
+   - Release locks and finish or roll back multi-field mutation before entering any nested dispatch.
+   - A recursive lock removes self-wait while exposing intermediate state; it does not restore the
+     invariant.
+4. Build a wait-for graph that includes delivery context.
+   - Add edges for thread waits, locks, synchronous sent messages, callbacks posted to the UI,
+     dispatcher operations, RPC or COM callbacks, portal responses and owner-close paths.
+   - Mark which run-loop mode, main context, priority, event class, thread affinity or message path
+     must execute each completion.
+5. Classify the failure precisely.
+   - Deadlock has a closed wait cycle.
+   - Starvation has a required ready source that the active loop, filter, priority or context does
+     not dispatch.
+   - Livelock keeps dispatching or reposting without advancing the request state.
+   - Stale continuation resumes an old outer frame after owner, model, selection or visual tree
+     authority changed.
+6. Review nested-loop admission and exit.
+   - Name the only APIs or signals that actually end the inner loop. General application quit,
+     cancellation request, owner disposal or transport close may not be that signal.
+   - Ensure filters, input disable, capture and owner selection do not remove the human or automated
+     path that creates exit.
+7. Reject manual pumping as completion proof.
+   - A loop that repeatedly processes events can starve lower-priority work, mishandle deferred
+     destruction, admit more producers than it drains, or keep the request state unchanged.
+   - Replace it with an explicit asynchronous completion and a bounded owner lifecycle.
+8. Treat platform behavior as a matrix.
+   - Distinguish queued messages from synchronous calls, broad message pumps from mode-filtered run
+     loops, framework dispatcher frames from native loops, recursive main contexts from portal
+     process boundaries, and blocking dialog APIs from callback or signal APIs.
+   - Read [Modal Loop and Reentrancy Checklist](references/modal-loop-reentrancy-checklist.md) for
+     the framework, design and diagnostic matrices.
+   - Distinguish synchronous return from thread sleep, input modality from state isolation, posted
+     work from synchronous or nonqueued dispatch, outer loop shutdown from inner session exit, and
+     deferred destruction from function-scope lifetime.
+9. Break the current callback stack before presenting interactive UI.
+   - Copy stable request data, return from the host callback, then enqueue presentation on the
+     owning UI context.
+   - Do not hide the same nested loop behind a future immediately blocked by `.wait`, `.get`,
+     `.Result`, or equivalent synchronization.
+10. Model each interactive request explicitly.
+    - Transition owner-scoped state through idle, presenting, awaiting result, applying or canceled,
+      and done. Enter presenting before any call that can reenter.
+   - Give every request and owner a generation. Coalesce equivalent requests, queue ordered work,
+     or return busy according to policy; do not create unbounded dialog stacks.
+   - Set the admission state before any call that may pump. Bind loop object, exit token, parent
+     session, owner-disable lease, capture state and input generation to that session.
+   - Route user close, cancellation and worker completion through one atomic
+     `TryComplete(sessionId, result)`. Choose one commit owner: completion signal or synchronous
+     return path, not both.
+11. Revalidate state after user think time.
+    - Store stable entity IDs, capability tokens and expected revisions rather than indexes,
+      iterators, object pointers, transient paths or selected-object copies.
+    - Before applying the result, verify owner existence, generation, entity revision, permission
+      and destination. Recompute or reject stale results.
+12. Tie cancellation to owner lifecycle.
+    - Owner close, document replacement, shutdown and explicit cancel complete the local request
+      exactly once. A provider or portal response is not required to arrive after cancellation.
+   - Late success, failure or response signals become idempotent no-ops after terminal completion.
+   - Treat hidden and closed as different lifecycles. A reusable dialog gets a new display
+     generation, fresh cancellation ownership and explicit subscription reset every time.
+   - Validate weak owner or dialog identity and session generation after the nested call returns;
+     return does not prove the caller object survived inner dispatch.
+13. Keep long or failure-prone work outside the dialog callback.
+    - Return the user's choice, close presentation, then perform file I/O, parsing, network or remote
+      validation in owned asynchronous work. Report failures inline instead of recursively opening
+      another blocking dialog.
+14. Preserve capability-bearing picker results.
+    - Do not collapse URI, access token, sandbox grant, remote object or provider handle into a
+      local path string when later access depends on that authority.
+15. Instrument reentrancy without changing it.
+    - Record modal enter and exit, depth, owner, request, call site, mode or context, exit reason,
+      queued versus synchronous dispatch, callback start and end, wait edges and state hashes in a
+      bounded low-overhead ring.
+    - Correlate stacks, CPU state and system traces. A watchdog gathers evidence; it does not
+    forcibly dismiss destructive UI.
+16. Read [Nested Modal State and Lifetime Checklist](references/nested-modal-state-lifetime-checklist.md) when nested sessions can mutate owners, collections, input generations, commit paths, deferred deletion, or shutdown state.
+17. Require adversarial evidence.
+    - Force callback reentry before outer return, completion on an excluded mode or context,
+      high-priority source starvation, synchronous call cycles, repeated confirmation, owner close,
+      stale entity revision, cancellation without provider response, immediate provider response,
+      nested input capture and shutdown during presentation.
+    - Assert bounded modal depth, state progress, exactly-once completion, no held lock across nested
+      dispatch, no stale result application, no orphan owner disable or capture, and a replayable
+      wait or causal graph.
+    - Also force parent deletion, collection mutation during the nested call, double completion,
+      nested owner disable, wrong-session exit, deferred deletion, stale queued input after modal
+      exit, dialog reuse, continuation-before-return, and progress backlog.
+    - If configured proof is unavailable, report static reentrancy risk instead of approving the
+      path.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Nested dispatch, outer stack, modal depth, owner, request, invariants, dispatch contexts, wait
+  graph, exit condition, platform behavior, request state machine, cancellation, stale-result guard,
+  diagnostics and tests are explicit.
+- Lock-held modal entry, sync-over-async UI wait, synchronous call cycles, wrong run-loop mode or
+  context, priority starvation, manual-pump livelock, recursive confirmation, wrong owner disable,
+  callback-hosted modal UI, stale routed event, quit-as-dialog-exit, late provider response and
+  capability loss are fixed or reported.
+- Session admission after the pump starts, half-applied invariants, duplicated domain commands,
+  caller deletion, iterator invalidation, double commit, Boolean modal ownership, focus-triggered
+  mutation during construction, hidden-instance reuse, double cleanup, wrong-loop exit and
+  post-modal stale input are fixed or reported.
+- Reentrancy safety claims are backed by configured tests, framework evidence matched to current
+  code, causal or wait traces, or labeled as static review risk.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `lint`
+- `build`
+- `test_related`
+- `test`
+- `test_audit`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Prefer the narrowest configured intent that covers the changed UI reentrancy boundary and template
+surfaces. Do not infer raw profilers, message hooks, system traces, live dialogs, portal calls,
+watchers, or platform diagnostics outside the command contract.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If the nested loop, outer frame, exit condition or required delivery context cannot be named,
+  report the path as unreviewable for reentrancy.
+- If safe repair requires framework migration, async public API change, native instrumentation,
+  system tracing, portal integration or a deterministic harness outside scope, report that boundary.
+- If diagnostics alter timing, allocate, block, acquire application locks or consume messages in the
+  hot hook, remove or redesign the observer before trusting its result.
+- If configured tests cannot force nested dispatch, report the missing manual or integration
+  evidence and do not infer a raw command.
+- If a configured command fails, preserve the failing invariant, request trace and first relevant
+  output before editing again.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Modal-loop reentrancy boundary reviewed
+- Outer stack, modal depth, owner, request, invariant, dispatch context, wait graph, exit condition,
+  platform, modal session, completion and commit authority, owner-disable and capture ownership,
+  object lifetime, deferred deletion, input generation, request-state, cancellation, stale-result,
+  capability, diagnostic and test findings
+- Reentrancy fixes made or recommended
+- Evidence level: configured-test evidence, framework evidence, causal or wait trace, static review
+  risk, manual-only, missing, or not applicable
+- Command intents run
+- Skipped reentrancy diagnostics and reasons
+- Remaining modal-loop reentrancy risk

package/templates/default/locales/en/.mustflow/skills/modal-loop-reentrancy-review/references/modal-loop-reentrancy-checklist.md

@@ -0,0 +1,290 @@
+# Modal Loop and Reentrancy Checklist
+
+Use this checklist when one event-processing stack can dispatch another event before the outer
+handler returns. Confirm framework and version behavior from current repository or official sources;
+do not treat this matrix as a substitute for platform evidence.
+
+## Contents
+
+1. [Failure classification](#failure-classification)
+2. [Outer-frame inventory](#outer-frame-inventory)
+3. [Wait and delivery graph](#wait-and-delivery-graph)
+4. [Framework behavior matrix](#framework-behavior-matrix)
+5. [Unsafe patterns](#unsafe-patterns)
+6. [Asynchronous interaction contract](#asynchronous-interaction-contract)
+7. [State and owner revalidation](#state-and-owner-revalidation)
+8. [File-picker authority](#file-picker-authority)
+9. [Tracing without observer effects](#tracing-without-observer-effects)
+10. [Platform diagnostic routing](#platform-diagnostic-routing)
+11. [Fault matrix](#fault-matrix)
+12. [Invariants](#invariants)
+13. [Skill handoffs](#skill-handoffs)
+
+## Failure classification
+
+Distinguish these outcomes before changing code:
+
+| Class | Observable structure |
+| --- | --- |
+| deadlock | a closed wait cycle prevents required progress |
+| starvation | required work is ready or posted but the active mode, context, priority or filter never dispatches it |
+| livelock | callbacks and messages run while the request state never advances |
+| stale continuation | the outer handler resumes after owner or model authority changed |
+| reentrant corruption | an inner callback observes or mutates a partially updated invariant |
+| human-path starvation | wrong owner, capture or disable policy removes the only user exit |
+
+A responsive window, nonzero CPU, or active message stream does not rule out livelock or starvation.
+
+## Outer-frame inventory
+
+At each nested-loop boundary record:
+
+- outer handler and originating event;
+- current thread and affinity;
+- call site and modal depth;
+- owner, document, surface and request identity;
+- locks, transactions and guards still held;
+- iterators, object pointers, visual elements and selected items still referenced;
+- multi-field state currently between valid states;
+- callbacks or host contracts waiting for the outer return;
+- code that resumes after the inner loop exits;
+- actual exit signal and terminal-result owner.
+
+Attack the assumption that a local variable remains valid merely because its stack frame still
+exists.
+
+## Wait and delivery graph
+
+Model both waits and the context needed to satisfy them.
+
+Nodes can include:
+
+- UI and worker threads;
+- mutexes, events, semaphores and condition variables;
+- tasks, futures and dispatcher operations;
+- queued messages and synchronous sent messages;
+- COM, RPC, IPC and plugin calls;
+- run-loop modes, main contexts and source priorities;
+- portal or provider request handles;
+- dialog owner, capture and input-disable state;
+- user action required to close the request.
+
+For each completion edge, record:
+
+- who is waiting;
+- what must run;
+- target thread or context;
+- required mode and priority;
+- whether it is queued, sent, invoked, signaled or polled;
+- which filter can defer or consume it;
+- whether owner shutdown removes the callback path.
+
+A posted completion is not progress evidence when its context is not active.
+
+## Framework behavior matrix
+
+Use this as a question list, not a frozen compatibility promise:
+
+| Family | Boundary to verify |
+| --- | --- |
+| native Windows dialog | owner disable, nested message dispatch, queued versus synchronous messages, actual dialog termination |
+| dispatcher-based Windows UI | nested dispatcher frame, priorities, routed-event continuation, deferred operations |
+| COM apartment UI | apartment type, outgoing-call pumping, callback delivery and synchronous call cycles |
+| AppKit | modal versus sheet API, active run-loop mode, tracking modes and source registration |
+| Qt | blocking dialog execution, local loop flags, deferred deletion, thread affinity and queued signals |
+| GLib or GTK | recursive main loop, selected main context, source priority, recursion policy and portal boundary |
+| desktop portal | process boundary, response subscription ordering, cancel semantics and capability result |
+| embedded browser or WebView | callback serialization, host return requirement, UI posting and reentrancy restrictions |
+
+Do not describe all platforms as one global message queue. Mode filters, recursive contexts,
+synchronous calls, thread affinity and external portal processes create different failure shapes.
+
+## Unsafe patterns
+
+Reject or prove safe:
+
+- lock held while opening a blocking dialog;
+- partially updated model exposed across nested dispatch;
+- UI thread waiting for a completion posted to the UI thread;
+- two threads or components issuing synchronous calls back into each other;
+- completion source attached only to a mode or context not run by the modal loop;
+- always-ready high-priority source starving completion or cancel;
+- loop flags excluding the only socket, input or close event;
+- `while (!done) processEvents()` or equivalent busy pumping;
+- confirmation handler opening another confirmation before changing state;
+- wrong owner, capture or disable target;
+- callback opening blocking UI before returning to a serialized host;
+- general application quit treated as the nested dialog's exit;
+- future-returning wrapper immediately blocked by the caller;
+- global `isDialogOpen` or reentrancy boolean without owner and generation;
+- iterator, selected index or object pointer retained across user think time;
+- cancellation waiting forever for an optional provider response.
+
+## Asynchronous interaction contract
+
+Prefer a nonblocking request:
+
+`Idle -> Presenting -> AwaitingResult -> Applying | Cancelled -> Done`
+
+Required properties:
+
+- enter `Presenting` before any call that can synchronously invoke callbacks;
+- stable request, owner and generation identity;
+- exactly one terminal result;
+- explicit duplicate policy: coalesce, queue or busy;
+- bounded queue and no recursive dialog stack;
+- presentation posted after the current callback returns;
+- result delivered by task, future, signal or callback without sync-over-async;
+- owner close and explicit cancel complete locally;
+- late result is an idempotent no-op;
+- apply step revalidates target and authority;
+- long work begins after presentation closes.
+
+Scope modal behavior to the affected window or document when product semantics allow unrelated work
+to continue.
+
+Prefer reversal and recovery over confirmation theater: undo, soft delete, versioning, preview,
+staged apply and atomic replace can remove the need for a blocking question.
+
+## State and owner revalidation
+
+Snapshot stable intent, not transient objects:
+
+- entity or document ID;
+- expected revision or generation;
+- requested action and parameters;
+- owner ID and lifecycle generation;
+- permission or capability identity;
+- request ID and creation context.
+
+After completion verify:
+
+- owner still exists and owns the request;
+- target still exists;
+- expected revision or precondition still holds;
+- permission or capability remains valid;
+- destination surface or document is current;
+- result has not already completed or been canceled.
+
+Recompute against current state or reject. Do not blindly continue the old routed event or mutate
+the old selection.
+
+## File-picker authority
+
+A picker result can include authority beyond a path:
+
+- URI or provider identifier;
+- display name and metadata;
+- sandbox grant, bookmark, token or file descriptor;
+- remote object or lazy provider handle;
+- capability lifetime and persistence rule.
+
+Preserve the authority-bearing result type. A local path string may not remain accessible across
+processes, sandbox boundaries, remote providers or later runs.
+
+Portal-like flows need:
+
+- response subscription before or atomically with request publication;
+- stable request handle and owner;
+- local cancel completion even when no later response arrives;
+- late response suppression;
+- capability cleanup;
+- result schema and lifecycle evidence.
+
+## Tracing without observer effects
+
+Record a modal or interaction span with:
+
+- monotonic time and global or thread-local sequence;
+- request, owner, dialog and event identity;
+- UI thread and source thread;
+- call site and modal depth;
+- current mode, main context or dispatcher priority;
+- enter, callback, wait, wake, exit and completion events;
+- exit or cancellation reason;
+- state hash before and after reentrant callbacks;
+- queued versus synchronous dispatch;
+- target thread and wait edge.
+
+Use fixed-size numeric records in a bounded memory ring on hot hooks. Avoid file I/O, formatting,
+allocation, application locks and state mutation in the observer.
+
+Capture full thread stacks and CPU state at the hang point. Busy repeated frames indicate a
+different class than a low-CPU blocking wait.
+
+Build a wait-for graph from both system objects and application-level tasks, dispatchers, RPCs and
+request handles.
+
+## Platform diagnostic routing
+
+Select only diagnostics authorized by the command contract and current platform:
+
+- Windows: queued-message, sent-message and modal-filter paths are distinct; correlate application
+  spans with thread waits and system traces.
+- Dispatcher frameworks: record operation posted, started, completed or aborted, priority, nested
+  frame depth and resumed event age.
+- AppKit: record run-loop activities, active mode, local event dispatch and signposted interaction
+  spans.
+- Qt: record loop depth, dispatcher sleep and wake, filtered framework events and bounded native
+  events.
+- GLib or GTK: name sources and record context, priority, recursion, callback duration and readiness.
+- Portals: record request publication, response subscription, returned handle, cancellation and
+  terminal local task state.
+
+Observers must forward or preserve events. A diagnostic hook that consumes an event or changes
+priority invalidates the reproduction.
+
+## Fault matrix
+
+Cover relevant cases:
+
+| Fault | Expected result |
+| --- | --- |
+| callback reenters before outer return | invariant remains valid or reentry is deferred |
+| lock held at modal entry | assertion or structural prevention fires |
+| UI waits on UI-posted completion | wait graph exposes and implementation avoids cycle |
+| completion registered in inactive mode | request remains observable and design routes correctly |
+| high-priority source reposts continuously | completion and cancellation have bounded progress |
+| input or socket class excluded | exit path remains available |
+| manual pump receives new work continuously | state still terminates or manual pump is absent |
+| confirmation double click | one owner request is admitted |
+| owner closes while awaiting result | request cancels exactly once |
+| stale model revision after think time | result is recomputed or rejected |
+| provider responds immediately | subscription or continuation does not miss response |
+| provider omits response after cancel | local cancellation still completes |
+| old completion arrives after new generation | new request state is unchanged |
+| shutdown during presentation | no orphan disable, capture, task or callback remains |
+| tracing enabled | failure class and timing remain representative |
+
+Prefer deterministic reentry hooks and fake request providers over arbitrary sleeps.
+
+## Invariants
+
+Choose applicable executable invariants:
+
+- modal depth is bounded by policy;
+- no application lock or partial invariant crosses nested dispatch;
+- every interactive request has one owner and one terminal completion;
+- owner closure cannot leave an awaiting request alive;
+- old generations cannot apply results;
+- request state advances or reaches a bounded terminal state;
+- the exit event's source remains dispatchable;
+- cancellation does not depend on an optional remote response;
+- presentation does not occur inside a host callback that forbids reentrancy;
+- capability-bearing results retain required authority;
+- tracing does not block, allocate unboundedly, consume events or acquire application locks.
+
+## Skill handoffs
+
+- Use `race-condition-review` for parallel interleavings, happens-before, atomics and data races.
+- Use `concurrency-invariant-review` for lock order, condition variables, resource ownership and
+  shutdown outside the modal boundary.
+- Use `async-timing-boundary-review` for readiness, polling and waits after nested-loop risk is
+  removed.
+- Use `state-machine-pattern` to implement the interactive request lifecycle.
+- Use `frontend-accessibility-tree-review` for dialog semantics, focus trap, announcements and
+  keyboard behavior.
+- Use `file-path-handling` or the platform adapter skill for picker URI, capability and path
+  boundaries.
+- Use `provenance-license-gate` before copying platform hook or diagnostic examples.
+