恢复¶

interruption / dependency failure
  -> affected operation stops, falls back, or reports failure
  -> automatic recovery OR explicit retry              // depends on the failure
  -> fresh hold -> new audio -> release -> expected output // recovery endpoint

Launch -> read settings.json
├── Unknown keys -> ignored
├── Invalid field -> log its key and reason -> that field's default
│   └── Valid siblings and unrelated sections stay
├── Invalid JSON / unreadable file -> log why -> defaults in memory
└── Save over invalid settings -> preserve exact original first
    ├── settings.json.unreadable-<sha256>, owner-only; same bytes backed up once
    └── Backup fails / original cannot be read -> save fails, original stays

Escape -> nothing: the capture and every accepted job go on
older job + fresh capture -> both complete, in order

stale shortcut state
  -> no hold/pending gesture + no pending input       // required gates
  -> full key scan + >= 100 ms sampled neutrality
  -> rearm bookkeeping only                          // emits NO capture actions
  -> fresh hold -> release -> expected output

LOCKED + key release missed while hands-free          // would block the finish press
  -> same gates, scan, and neutrality
  -> clear key tracking, stay LOCKED                  // emits NO capture actions
  -> fresh shortcut press -> Finish

delayed pre-recovery input -> fenced                  // cannot corrupt the fresh hold

Command-Tab -> Tab still tracked (IDLE, DIRTY, or LOCKED)
  -> typing, Return, Shift …                          // don't matter
  -> binding press: the binding's own down edge
     ├── keyboard reported no modifiers after each tracked key's own press
     ├── only the binding's modifiers went down since
     └── tracked keys + every other modifier read up now  // same source as recovery
        -> clear tracked keys, fence input stamped before the press
           -> fresh press -> Start (IDLE, DIRTY) or Finish (LOCKED)
              ├── chord at the same tick -> Discard     // not fenced
              └── older delayed release of the key -> ignored
  -> any check fails -> press ignored (logged with reason + key_codes)
                     -> 100 ms poll as before
tracked key down in combined-session state but up in HID state  // #612
  -> reads as up for both the press check and the poll   // a latched Tab or Q
     no longer blocks every press until Hex restarts
tracked keyboard key reads down in both states but sent no key event,  // #1008
not even a key repeat, for 5 s (TRACKED_KEY_REPEAT_TIMEOUT)
  -> the press check treats it as released               // logged; mouse buttons excluded
     a Tab really held keeps repeating and still blocks the press
     (with key repeat turned off, a key held past 5 s no longer blocks it)
LOCKED + Escape -> Nothing, stale keys or not (#786)
fenced edges, edges before a disabled tap, suspension -> no neutral evidence

SecondaryFn 导航元数据
  ├── 带时间戳的修饰键变化证据说明 Fn 已松开
  │     -> 可因中立性忽略该元数据    // 完整扫描与延迟围栏保留
  └── Fn 被按住或状态未知 -> 将 Fn 保留为阻塞键

从快捷键匹配中全局剔除 Fn              // 不安全：不是恢复规则

事件点按被禁用
  -> 取消进行中的热键手势                     // 不会卡在录制中
  -> 使不确定的修饰键证据失效           // 不推断已松开
  -> 全新输入 -> 下一个有效手势 -> 预期输出

禁用事件（超时 | 用户输入）
  -> 重新启用每个点按                    // “macOS 禁用了事件点按；已重新启用”
  -> recover.tap-interruption
每 5 秒在点按线程上
  ├── 点按被静默禁用 -> 重新启用  // “事件点按在未通知的情况下被禁用”
  ├── 点按失效或重新启用失败 -> 重建  // “已重建事件点按”
  └── 创建失败 -> 下次检查重试    // “无法重建事件点按”，仅记录一次
  -> 按键或修饰键间隙 -> recover.tap-interruption
点按线程持有用户发起的活动  // App Nap 无法限流它；允许空闲休眠

初始打开失败 或 流中断
  -> 取消不完整的捕获 + 丢弃陈旧音频  // 中断的音频不能返回
  -> 有界退避 -> 重新打开已解析的输入     // 暖麦克风重试
  -> 替换投递新的音频
  -> 全新捕获 -> 释放 -> 预期输出
设备拒绝以其默认格式打开流     // #988，Intel Smart Sound on Windows
  -> 记录被拒绝的格式（声道、Hz、采样格式） // audio/input_format
  -> 尝试其列出的其他格式（F32、I16、U16、I32），最多 12 次
  -> 均无法打开 -> 默认格式的错误（含其格式）进入恢复流程
完全没有输入设备（macOS）
  -> 名称无法读取的设备被跳过     // audio::device_name，绝不显示
  -> 有界恢复；`hex status` 监听器：“No microphone”
启动时或中断后没有输入可打开（Linux） // #937
  -> 每次中断只报告一次“could not open the microphone: …” // take_failure
  -> 持续重试期间保留最后一次失败；一旦成功打开则重置
监听器工作线程返回错误或崩溃（macOS）
  -> 状态：running false、“Stopped”、capture 未知 // 绝不显示“Enabled”
已保存的麦克风缺失或无法打开
  -> 系统默认设备暂代，设置不变      // audio::Selection
  ├── 列表中存在但无法打开 -> 使用有界退避重新查找
  └── 不在列表中 -> 在设备列表变更时重新查找 // macOS 报告设备接入
                    └── Windows、Linux：有界退避，仅在切换时记录
  -> 找到后 -> 在捕获空闲时切换回来        // 不在挂起的启动或尾部期间
MacBook 盖子合上（macOS）                            // 内置麦克风已关闭但仍在列表中
  -> 内置麦克风与 Hex Microphone 一样被跳过  // AppleClamshellState，每次解析时读取
  ├── 耳机插孔麦克风（BuiltInHeadphoneInputDevice UID，或内置
  │   输入的 emic/line 数据源）-> 保持可用：在列表中、可选择、
  │   跟随默认设备，并可暂代（#712）
  ├── 默认或已保存的麦克风是内置的 -> 第一个其他真实输入暂代
  │     -> 设置：“… 在盖子合上时关闭，因此 Hex 正在收听 …”
  ├── 没有其他输入 -> “内置麦克风在盖子合上时处于关闭状态”
  └── 盖子打开或合上 -> 像设备列表变更一样重新解析 // IOKit clamshell 通知
        -> 在捕获空闲时切换
蓝牙默认输入（macOS，启用了 avoid_bluetooth_microphone） // 传输类型，每次解析时读取
  -> 内置麦克风暂代，否则使用第一个其他真实输入
  ├── 没有其他可用输入 -> 使用蓝牙默认设备
  └── 设置变更 -> 像设备列表变更一样重新解析 -> 空闲时切换
虚拟输入或 iPhone Continuity 麦克风（macOS：ccwd/ccwl 传输） // #1100
  -> 绝不暂代：手机会弹窗提示且可能无法打开
  ├── 盖子合上且没有其他设备 -> 显示“内置麦克风在盖子合上时处于关闭状态”
  └── 默认设备、已保存的麦克风或 --device -> 按指定名称使用

热流仍在运行但只传送全零数据（macOS，#1122）
  -> 该次听写按近乎静音丢弃，与之前相同
  -> 其结束像流失败一样重新打开麦克风 // 仅记录一次
  -> 下次听写从新流录制

打开的流停止传送音频但不报错（任意 OS，#1206）
  -> 4 秒无数据块（STREAM_STALL_TIMEOUT）-> 按流失败处理
  -> 像任何中断的流一样重新打开，无论空闲与否 // 记录“microphone stopped delivering audio”

程序化听写（本地 API）在流中断或出现间隙时
  ├── 丢失前已送达的音频 -> 按其 ID 保留 // recover.programmatic-loss
  │     -> /finish 转录它；/cancel、心跳和租约仍然生效
  │     -> 当 /finish 在丢失被读取之前到达时同样适用（take_loss）
  └── 自开始以来没有音频（打开失败，或仅有 pre-roll）
        -> /finish 应答 409 microphone-lost

press A -> asynchronous open A
  -> release/cancel before ready -> abandon A
press B -> asynchronous open B
  ├── late ready A -> reject                          // belongs to abandoned open
  └── ready B -> capture B -> finish -> expected output
                   └── capture idle -> close device   // accepted jobs do not keep it open

release-when-idle enabled + capture idle -> stop retries
warm mode enabled during pending capture -> preserve capture; retry after cancellation

cold open -> selected microphone fails to open
  -> retry it twice, 100 ms apart -> then the system default (logged)
ready stream fails while the press is held
  ├── before the 300 ms hold threshold -> back to pending, reopen for the same press
  │     ├── release before ready -> discard
  │     └── ready -> capture from the original press -> expected output
  └── after the threshold -> fail with "Microphone capture was interrupted"
CoreAudio processor overload (Xrun) -> warn and keep the stream // not a failure
gap in the microphone timeline (any OS, warm or cold)
  ├── 50–250 ms -> filled with silence, capture continues // logged, #619
  └── over 250 ms -> fail as a capture discontinuity

capture A fails -> finish/cancel A -> preserve A's terminal failure
start capture B -> new generation                     // fences obsolete notifications
  ├── late failure/ready A -> cannot finish, fail, or activate B
  └── B's own audio -> finish B -> expected output

command model loads in background
  ├── slow/failing loader -> command preparation unavailable
  └── listener remains responsive -> fresh hotkey capture -> expected output

new model loads beside the running one -> GPU out of memory -> CPU copy loads
  -> the CPU copy is dropped (not swapped in); the GPU isn't remembered as failed
  -> once nothing records or transcribes -> engine drops its model, then loads
     the new one in its place (GPU again, CPU only if it still doesn't fit)
  -> commands sent meanwhile wait for the load; nothing recorded is lost

microphone timeline
  ├── active dictation -> retain continuous audio -> expected output
  └── command backlog exceeds bound
        -> invalidate stale generation + reset recognition
        -> discard stale audio/updates                // no stale command may execute

command recovery -> next fresh dictation still works  // not just an emptied queue

ordinary dictation -> corrections -> optional rewrite -> transformations -> paste
                                      │                  │
                                      v                  v
                             rewrite fails       chain fails
                             -> corrected text   -> chain's input // discard partial results
                             // the log says why: rewrite off for the mode, or the failure reason

later request -> expected output                       // recovery still needs observation

listener worker fails -> reap worker -> show failure
  ├── Retry -> new managed listener -> fresh capture -> expected output
  └── Dismiss -> clear error                            // not evidence of recovery

close the window -> Hex keeps running
  └── uncommitted shortcut capture -> cancel edit -> restore prior listening

Hex crashes -> systemd restart-on-failure (no window) OR explicit hex start
  -> hex / hex status -> live state, not stale log state

hex quit / Quit Hex -> drain accepted work -> release microphone and hotkeys -> exit 0

listener starts -> one session, one BindShortcuts: Hex's shortcuts only
  └── KDE -> remove the stale `cancel` and `cancel-dictation` entries first
desktop closes the shortcuts session -> cancel active capture
  -> listener stops with an error -> Retry / hex start binds again
X11, Annotate drawing -> grab Escape (AnyModifier, else bare + lock variants)
  └── BadAccess -> warn once, keep drawing; other grab errors stop the listener

listener starts -> no GlobalShortcuts portal
  -> warn (desktop name, restart-the-portal hint) -> hex commands drive dictation
  -> check again on its own thread: after 15 s, doubling up to every 2 min
     └── portal appears (e.g. xdg-desktop-portal restarted) -> bind shortcuts as usual

GUI startup -> require OS main thread -> initialize_layout // recover.keyboard-layout
  -> publish complete snapshot BEFORE settings/workers/Rune
     ├── cached character -> keycode
     ├── missing ASCII character -> filled from ASCII-capable layout
     └── Command layer (UCKeyTranslate with cmdKey) -> separate map
                                     // no worker-side TIS/TSM query

Selected input source changes (Dvorak -> U.S.)       // recover.keyboard-layout-change
  -> observer marks it -> pump on the main thread -> refresh_layout
  -> rebuild with the same fills -> publish whole       // workers see old or new
  -> changed -> resolve runtime shortcuts again from the last applied settings
     ├── letter key -> the key that types the letter now
     ├── other keys -> recorded key code
     └── listener rebinds each shortcut once its machine is idle

Synthetic shortcut with Command (⌘V)
  ├── Command layer has the character -> that keycode // "Dvorak – QWERTY ⌘"
  └── otherwise -> plain snapshot as above
Shortcuts without Command -> plain snapshot only

Headless lookup without snapshot -> shared native lock -> current layout query
  -> current layout misses ASCII character -> ASCII-capable fallback
Concurrent snapshot construction -> same lock          // serialized, not a separate race

Retained regression
├── cold-lookups -> native queries serialized; headless lookups remain live
├── cold-mixed -> initialization and lookups coordinate through the same lock
├── warm-hits -> exactly one native snapshot acquisition
└── warm-misses -> exactly one native snapshot acquisition, not just "no crash"

After explicit initialization -> further hits AND misses add zero native queries

remapped keyboard -> Quartz modifier event -> InputEvent::Flags
                                              └── keycode discarded
side-less Control fixture -> does not prove remapped-key identity
listen-only native metadata -> establish distinguishability before choosing a fix

reported mute failure / missed hold
  -> record build + permissions + mic mode + exact devices
  -> observe hold -> capture -> release -> result       // missing native evidence

ownership/timing tests -> device-specific root cause    // UNSAFE inference

transformation runs past its timeout -> interrupted -> that call fails
  // 1 s, or 30 s when the config uses fetch or node:child_process; 60 s cap
  -> its requests abandoned, its process trees killed
  -> transformation chain -> its input is kept           // ordered processing goes on
  -> later call on the same config -> succeeds
fetch or exec before the person allows the config -> throws -> input kept
config load past 2 s or past 64 MiB -> rejected -> previous config stays active

Chromium 155/156 frontmost? type instead (#212); else publish clipboard -> post Paste
  ├── settle for 100 ms -> allow next output
  └── schedule restore after 500 ms -> restore only if still owned
target consumes later?                                // no consumption acknowledgment

controlled delayed consumer -> output A -> output B -> restoration
                                                      // missing isolated evidence