tirtc-device-builder 0.8.0 → 0.8.1

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "tirtc-device-builder",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Codex workflows for building and validating TiRTC device firmware across supported chip platforms.",
   "author": {
     "name": "TangeAI",

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 This project follows Semantic Versioning.
 
+## 0.8.1
+
+- Separate rapid `idf.py flash` iteration from portable evidence-bundle export,
+  so active development keeps the normal `build/` tree and does not require a
+  new multi-BIN archive for every device test.
+- Add deterministic ESP-IDF application-descriptor inspection for explicit
+  firmware versions, application-BIN SHA-256, and full ELF SHA-256 matching.
+- Add product-control rules that distinguish MCU buttons, boot straps, reset
+  lines and PMIC/power-latch keys across baseboard and battery-carrier variants,
+  and route button gestures through the runtime's intent queue.
+- Add trace-based diagnosis for repeated AI/H5 downlink audio across SDK
+  callbacks, bounded queues, playback, resampling, and codec/I2S writes.
+
 ## 0.8.0
 
 - Add an evidence-backed board identity and curated registry workflow with exact,

package/README.md

@@ -549,7 +549,19 @@ python3 ~/.codex/skills/tirtc-esp32-builder/scripts/install_video_gate.py .
 idf.py build
 ```
 
-只安装实际请求能力的门禁。编译后把 BIN/ELF 的路径、大小和 SHA-256 写入 Hardware IR 的 `build_evidence.artifacts[]`，再运行 build 阶段评估。编译成功但语义门禁缺失或失败时只能记录 `COMPILE_PASS / CAPABILITY_BLOCKED`。
+只安装实际请求能力的门禁。编译后先核对固件内嵌版本、应用 BIN
+SHA-256 和完整 ELF SHA-256：
+
+```bash
+python3 ~/.codex/skills/tirtc-esp32-builder/scripts/firmware_identity.py \
+  build/<app>.bin --elf build/<app>.elf --expect-version <expected-version>
+```
+
+随后按
+[`firmware-delivery.md`](skills/tirtc-esp32-builder/references/firmware-delivery.md)
+选择快速真机迭代或可移植证据包；该文档也规定从 `build/` 记录迁移到
+`artifacts/` 时如何保持 Hardware IR 和报告一致。编译成功但语义门禁缺失
+或失败时只能记录 `COMPILE_PASS / CAPABILITY_BLOCKED`。
 
 生成器会把 TiRTC SDK 复制到工程的 `third_party/tirtc/`。此后工程不再依赖 `tirtc-server-example`，但换机编译仍需准备兼容的 ESP-IDF 5.5.x 工具链。
 
@@ -599,7 +611,10 @@ cd /absolute/path/my-esp32-device
 idf.py -p /dev/ttyACM0 flash monitor
 ```
 
-使用 `Ctrl+]` 退出 ESP-IDF Monitor。多个串口同时存在时，需要通过 USB 拔插、设备标识或芯片探测确认目标，不能默认烧录第一个端口。
+普通开发烧录优先使用这一条命令，让 ESP-IDF 从当前构建目录解析
+bootloader、分区表和应用镜像；无需手工维护多条 `esptool.py` 地址参数。
+使用 `Ctrl+]` 退出 ESP-IDF Monitor。多个串口同时存在时，需要通过 USB
+拔插、设备标识或芯片探测确认目标，不能默认烧录第一个端口。
 
 ### Wi-Fi 凭证和设备绑定
 
@@ -911,8 +926,8 @@ metadata 中的版本、标签、上游 commit 和期望 SHA-256 必须与本地
 
 ```bash
 npm test
-git tag -a v0.8.0 -m "v0.8.0"
-git push origin v0.8.0
+git tag -a v0.8.1 -m "v0.8.1"
+git push origin v0.8.1
 ```
 
 不要重复发布已经存在的 npm 版本。版本变化同步更新 `package.json`、`.codex-plugin/plugin.json` 和发布说明。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tirtc-device-builder",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Install and run TiRTC device-development skills for Codex.",
   "license": "MIT",
   "author": {

package/skills/tirtc-esp32-builder/SKILL.md

@@ -98,18 +98,29 @@ H5/AI/call runtime behavior, read and install the applicable semantic contracts.
 Keep concrete board values in Hardware IR, contracts and adapter files rather
 than Skill defaults.
 
+When the product request includes a physical button, touch input, reset, power
+key, wake source or enclosure label, read
+[product-controls.md](references/product-controls.md). Treat the exact physical
+product as baseboard plus any carrier, PMIC and enclosure controls. Board input
+code emits bounded intents to the state-owning runtime; it does not own session
+lifecycle.
+
 ## 6. Build and assess
 
-Run focused tests, resolve managed components, validate the exact SDK
+Read [firmware-delivery.md](references/firmware-delivery.md) and select
+`development flash` or `evidence bundle` from the user's current goal. Run
+focused tests, resolve managed components, validate the exact SDK
 `manifest/build-contract.env`, install every applicable semantic gate, then run
 the ordinary ESP-IDF build. Requested call/VoIP features must be represented by
 the runtime/business contract and the unified arbiter implementation; an H5/AI-
 only starter cannot reach `BUILD_VERIFIED` for those features.
 
-Copy final BIN/ELF deliverables into project-relative `artifacts/`, record actual
-size and SHA-256 in Hardware IR, then run strict build assessment with `--project`
-and that exact hash. Compiler success with a missing feature gate is
-`COMPILE_PASS`, not product completion.
+Set an explicit firmware version, verify the application descriptor and full
+ELF identity with `firmware_identity.py`, and record the application-BIN hash
+with its exact label. Follow the selected delivery mode's artifact paths and
+retention rules, record actual size and SHA-256 in Hardware IR, then run strict
+build assessment with `--project` and that exact hash. Compiler success with a
+missing feature gate is `COMPILE_PASS`, not product completion.
 
 ## 7. Flash, verify, and learn
 
@@ -129,9 +140,9 @@ board; attach artifact evidence; add regression tests for generic invariants;
 then publish a new Skill/registry version. Never let an installed Skill mutate
 itself from conversation history.
 
-Remove machine-bound `build/` after the final assessment, retain verified
-project-relative artifacts, run `project_portability.py --export`, and return the
-project, Hardware IR, identity match, capability result, artifacts and report.
+Complete the selected mode's retention or export checks from
+`firmware-delivery.md`. Return the project, Hardware IR, identity match,
+capability result, exact artifacts, flash command when applicable, and report.
 
 ## Security boundary
 

package/skills/tirtc-esp32-builder/USAGE.md

@@ -102,6 +102,20 @@ python3 <skill-dir>/scripts/hardware_ir.py assess --phase hil \
 
 `init` 默认创建 schema v2；v1 仅用于兼容已有 H.264 IR。`BLOCKED` 表示资料已确认硬件/合同/资源或凭证策略不满足；`NEEDS_CONFIRMATION` 表示当前阶段仍有未知项或证据不足；`READY_TO_PORT` 表示可以生成并实现板级适配；`BUILD_VERIFIED` 表示精确 artifact 已通过源码、编译和 post-link 门禁；`HIL_VERIFIED` 还要求同一 SHA-256 的 L5/L6 运行证据。
 
+## 固件身份与烧录方式
+
+顶层 `CMakeLists.txt` 应在 `project()` 前设置明确的 `PROJECT_VER`。编译后
+核对应用 BIN 中的版本和完整 ELF SHA-256：
+
+```bash
+python3 <skill-dir>/scripts/firmware_identity.py build/<app>.bin \
+  --elf build/<app>.elf --expect-version <expected-version>
+```
+
+按 [firmware-delivery.md](references/firmware-delivery.md) 选择快速真机迭代或
+可移植证据包；模式转换时必须同步迁移 Hardware IR 与报告中的 artifact
+路径。普通开发烧录命令为 `idf.py -p <exact-port> flash monitor`。
+
 ## 当前边界
 
 ThingConnect 仓库提供 ESP32-S3 H5/AI 模板和生成器，但默认媒体适配器不包含特定开发板的摄像头、麦克风、选定视频路径、Wi-Fi 凭证方法和扬声器驱动。模板生成和编译成功只证明工程与协议骨架可用，不代表 Web 已经出图或 AI 音频已经通过实机验收。

package/skills/tirtc-esp32-builder/VERSION

@@ -1 +1 @@
-0.8.0
+0.8.1

package/skills/tirtc-esp32-builder/assets/lckfb-szpi-esp32s3-portable-prompt.md

@@ -7,7 +7,7 @@ $tirtc-esp32-builder
 前置条件（必须由开发者在启动本次 Codex 会话前完成，不属于本提示词内的操作）：
 
 ```bash
-npx --yes tirtc-device-builder@0.8.0 setup esp32 --install --force-skill
+npx --yes tirtc-device-builder@0.8.1 setup esp32 --install --force-skill
 ```
 
 该命令只允许在当前用户目录安装固定版本的 Skill、managed ESP32 Device Kit、ESP-IDF 和工具链；禁止 sudo、系统级包变更和修改 shell profile。安装完成后，开发者必须关闭原 Codex 会话，再从本 clean-room 工作区启动一个新会话，然后粘贴本提示词。
@@ -15,11 +15,11 @@ npx --yes tirtc-device-builder@0.8.0 setup esp32 --install --force-skill
 本轮第一步先只读运行：
 
 ```bash
-npx --yes tirtc-device-builder@0.8.0 --version
-npx --yes tirtc-device-builder@0.8.0 setup esp32
+npx --yes tirtc-device-builder@0.8.1 --version
+npx --yes tirtc-device-builder@0.8.1 setup esp32
 ```
 
-必须根据命令的实际输出和本机文件确认：npm 包为 0.8.0、已安装 Skill 的 `VERSION` 为 0.8.0、所选 Device Kit 的 `manifest.json` 中 `kit_version` 为 1.1.1，并且 Doctor 对 `--expected-kit 1.1.1` 输出 `OVERALL: PASS`。Plugin manifest 不属于这种 npm 安装方式的运行时前置条件，不得把不可访问的 Plugin 版本当作阻塞项。如果版本不一致、Skill 是在当前会话启动后才安装，或环境检查未通过，停止并报告前置条件不成立；不要在当前会话中替换 Skill 后继续生成工程。
+必须根据命令的实际输出和本机文件确认：npm 包为 0.8.1、已安装 Skill 的 `VERSION` 为 0.8.1、所选 Device Kit 的 `manifest.json` 中 `kit_version` 为 1.1.1，并且 Doctor 对 `--expected-kit 1.1.1` 输出 `OVERALL: PASS`。Plugin manifest 不属于这种 npm 安装方式的运行时前置条件，不得把不可访问的 Plugin 版本当作阻塞项。如果版本不一致、Skill 是在当前会话启动后才安装，或环境检查未通过，停止并报告前置条件不成立；不要在当前会话中替换 Skill 后继续生成工程。
 
 工作区与 clean-room 边界：
 - 将启动 Codex 时的当前目录定义为 `WORKSPACE_ROOT`。

package/skills/tirtc-esp32-builder/assets/report-template.md

@@ -64,9 +64,12 @@
 
 ## Firmware and flash record
 
+- Delivery mode (`development flash` or `evidence bundle`): `{{DELIVERY_MODE}}`
+- Application project/version: `{{FIRMWARE_PROJECT_VERSION}}`
 - Serial port/chip: `{{SERIAL_TARGET}}`
 - Project-relative firmware artifacts: `{{FIRMWARE_ARTIFACTS}}`
-- Firmware SHA-256: `{{FIRMWARE_SHA256}}`
+- Application-BIN SHA-256: `{{FIRMWARE_BIN_SHA256}}`
+- Descriptor/full ELF SHA-256: `{{FIRMWARE_ELF_SHA256}}`
 - Flash command/result: `{{FLASH_RESULT}}`
 
 ## Artifact-bound runtime evidence

package/skills/tirtc-esp32-builder/references/environment.md

@@ -63,13 +63,19 @@ the packaged S3 archive as a compatible fallback.
 
 SDK resolution is independent after generation: an explicit `--sdk-dir` wins, followed by `<project>/third_party/tirtc`, then the SDK packaged in the resolved Device Kit or legacy workspace. The generated project remains diagnosable after it is moved away from the Kit.
 
-Before copying a generated project to another machine, run:
+For the evidence-bundle mode defined in
+[firmware-delivery.md](firmware-delivery.md), run:
 
 ```bash
 python3 <skill-dir>/scripts/project_portability.py <generated-project> --export
 ```
 
-Copy source inputs only. Never export `build/`: CMake caches absolute source, toolchain, and Python paths from the originating machine. `managed_components/` may be regenerated from the committed `dependencies.lock`; the bundled `third_party/tirtc` SDK and its build contract must remain in the source package. CMake must invoke shell gates through `bash <script>` so the build does not depend on archive- or filesystem-specific executable bits.
+Run it on a delivery copy and export source inputs only. CMake caches absolute
+source, toolchain, and Python paths under `build/`; `managed_components/` may be
+regenerated from the committed `dependencies.lock`. The bundled
+`third_party/tirtc` SDK and its build contract must remain in the source package.
+CMake must invoke shell gates through `bash <script>` so the build does not
+depend on archive- or filesystem-specific executable bits.
 
 The export check also requires Hardware IR, every requested-feature semantic
 contract, `sdkconfig.defaults`, a referenced custom partition table, and each

package/skills/tirtc-esp32-builder/references/firmware-delivery.md

@@ -0,0 +1,83 @@
+# Firmware identity and delivery
+
+Read this reference whenever the task builds, flashes, hands off, compares, or
+retains firmware. Select the delivery mode from the user's immediate goal; do
+not force a release bundle onto a quick device-test loop.
+
+## Choose one mode explicitly
+
+### Development flash
+
+Use this mode for rapid build/flash/monitor iteration on one development
+machine. Keep the normal ESP-IDF `build/` tree and use the ordinary command:
+
+```bash
+idf.py -p <exact-port> flash monitor
+```
+
+Do not create a new archive or make the user manually flash bootloader,
+partition-table and application BIN files when `idf.py flash` can resolve the
+build metadata. Before flashing, record the application version and hash of the
+exact application BIN. A build assessment may bind to a project-relative file
+under `build/`; that evidence remains valid only while that exact file exists.
+
+If an experiment produces runtime evidence worth retaining, copy the unchanged
+BIN and matching ELF into `artifacts/` before the next rebuild, record their
+sizes and hashes, and update the report. Copying does not create a new firmware
+identity; a rebuild does.
+
+### Evidence bundle
+
+Use this mode for a portable handoff, release candidate, rollback image,
+retained HIL result, or source export. Keep project-relative copies of the exact
+application BIN and ELF, plus bootloader and partition-table files when the
+recipient needs manual flashing. Record byte sizes and SHA-256 values in
+Hardware IR, run strict build assessment, then run
+`project_portability.py --export` on the source-only delivery tree.
+
+When promoting a development build into an evidence bundle, copy the unchanged
+files first, then replace every retained `build/...` artifact path in Hardware
+IR and the report with its new `artifacts/...` path. Remove transient build
+records that are not being retained; do not merely add bundle records beside
+stale paths. Rerun strict build assessment against the copied application-BIN
+hash so the assessor reopens the new path. The source-only export is ready only
+when every `build_evidence.artifacts[]` path exists outside `build/` and the
+matching report identifies the same hashes.
+
+Only this export workflow requires removal of the machine-bound `build/` tree.
+Do not delete it during active iteration, and never delete a user-owned build
+tree merely to make a report look portable.
+
+## Make firmware self-identifying
+
+Set an explicit, human-readable `PROJECT_VER` before `project()` in the top-level
+ESP-IDF `CMakeLists.txt`. Keep it at 31 UTF-8 bytes or fewer so it fits the
+`esp_app_desc_t.version` field with its terminator. Use a label that states what
+the image is: for example `audio-repro.2`, `button-test.1`, `fix.3`, or a release
+version. A build that deliberately preserves a known bug is a reproduction or
+diagnostic image, not a fix.
+
+At boot, log `project_name`, `version`, build date/time, IDF version, and the
+full ELF SHA-256 from `esp_app_get_description()` or
+`esp_app_get_elf_sha256()`. If the product has a console, expose the same fields
+through `version` or `status`. This lets a tester distinguish a successful
+flash of the wrong image from a runtime regression.
+
+Verify the built application BIN before flash or handoff:
+
+```bash
+python3 <skill-dir>/scripts/firmware_identity.py build/<app>.bin \
+  --elf build/<app>.elf --expect-version <expected-version>
+```
+
+The script reads the embedded ESP-IDF application descriptor, verifies the
+explicit version, and confirms that the supplied ELF's full SHA-256 matches the
+descriptor. It accepts an application BIN, not a merged whole-flash image.
+
+## Name hashes precisely
+
+The outer application-BIN SHA-256 and the descriptor's full ELF SHA-256 identify
+different files. Record both with unambiguous labels; do not call either one
+simply “firmware hash.” Bind Hardware IR artifacts and HIL observations to the
+exact retained artifact SHA required by the assessor, and include the boot-log
+version/full ELF hash so the physical device can be reconciled with that record.

package/skills/tirtc-esp32-builder/references/porting-risks.md

@@ -62,9 +62,37 @@ Disable Wi-Fi power saving for the realtime baseline unless the product contract
 
 Confirm SDK send return semantics and callback payload lifetimes from the selected SDK version. Keep SDK callbacks bounded and copy payloads before returning.
 
+## Repeated or duplicated downlink audio
+
+Do not label a build as a fix merely because it adds logs or makes the symptom
+less frequent. First produce a self-identifying reproduction build, then count
+the same frame across four boundaries: TiRTC receive callback, accepted queue
+item, playback dequeue, and codec/I2S write. Include mode and connection
+generation, stream/media type, payload length, bounded queue depth/drop counters,
+and an available transport sequence or timestamp. Sample payload hashes only as
+diagnostic evidence; do not blindly discard equal hashes because silence or
+legitimately repeated encoded frames may be identical.
+
+Carry one local trace ID from the accepted callback through queue and playback,
+and record write offset, requested bytes, returned bytes, and cumulative bytes.
+Multiple codec/I2S writes are valid when a frame is deliberately chunked or a
+partial write advances the offset; a local duplication exists only when the
+same byte/sample range is committed more than once or cumulative output exceeds
+the frame's decoded contract. Repeated callbacks with the same available
+transport identity point upstream or into SDK delivery. Unique downlink frames
+heard repeatedly require checking resampling, DMA/I2S replay and acoustic
+feedback separately. On stop/reconnect, reject stale generations and drain or
+invalidate queued audio. Verify the correction with repeated AI sessions, rapid
+stop/start, delayed callbacks and H5 recovery against the exact reproduction and
+candidate-fix firmware identities.
+
 ## Artifact discipline
 
-Record BIN/ELF SHA-256 for every build used in HIL. Runtime evidence applies only to the exact artifact. Diagnose one failing invariant, make the smallest correction, rerun that layer, and preserve the comparison in the report.
+Follow [firmware-delivery.md](firmware-delivery.md). Record the explicit firmware
+version, application-BIN SHA-256 and descriptor/full ELF SHA-256 for every build
+used in HIL. Runtime evidence applies only to the exact artifact. Diagnose one
+failing invariant, make the smallest correction, rerun that layer, and preserve
+the comparison in the report.
 
 Local intermediate snapshots may be ignored, but the Hardware IR, semantic
 contracts, `dependencies.lock`, custom partition input, and the artifact named

package/skills/tirtc-esp32-builder/references/product-controls.md

@@ -0,0 +1,76 @@
+# Product controls, reset, and power
+
+Read this reference when the product has buttons, touch inputs, reset controls,
+power keys, wake sources, or enclosure labels. Concrete pins and electrical
+behavior belong in the exact board/carrier evidence and adapter, never in this
+Skill.
+
+## Identify the physical product, not just the baseboard
+
+A retail or battery-powered device may combine a compute board with a carrier,
+PMIC, latch circuit, flex PCB, or enclosure controls that are absent from the
+baseboard schematic. When a user's physical observation conflicts with the
+available schematic, treat it as evidence of a missing or different variant.
+Do not declare a working control nonexistent. Request or inspect the exact
+carrier schematic, PCB markings, photographs, BSP definitions, or safe probe
+results and keep the unresolved mapping explicit.
+
+Classify each physical label before assigning software behavior:
+
+- MCU-readable GPIO button or touch input;
+- boot-strapping input;
+- reset/enable line;
+- PMIC or hardware power-latch control;
+- I/O-expander input;
+- indicator with no input function;
+- unknown control on a missing board layer.
+
+For an MCU-readable input, record the SoC GPIO, active level, external pull,
+debounce requirement, shared owner, wake capability, and any strapping role.
+Holding a strapping pin during reset can select a boot mode. A reset/enable line
+normally resets the MCU and cannot also be treated as an application button.
+A PMIC/latch power key and an MCU “enter deep sleep” action are different
+product contracts; do not substitute one for the other without circuit evidence.
+
+## Keep controls behind a narrow adapter
+
+Use a board/product-controls component to own GPIO setup, polling or ISR work,
+debounce, gestures, and boot-held suppression. It emits bounded product intents
+such as `AI_TOGGLE_REQUESTED`; it does not call TiRTC, HTTP, MQTT, media, or
+session lifecycle APIs from an ISR or polling callback.
+
+Prefer one `AI_TOGGLE_REQUESTED` event whose start/stop decision is serialized by
+the state-owning runtime. If the existing runtime exposes only separate start
+and stop intents, the adapter may map a public state snapshot to one of them,
+but the runtime must validate the intent again against its authoritative state.
+Define whether rapid gestures are queued, coalesced, or rejected so two reads of
+the same stale snapshot cannot silently violate the product behavior.
+
+The runtime remains responsible for session generation, callback ordering,
+media ownership, timeouts, cleanup, and late-event rejection. A toggle must
+define behavior for waiting, connecting, active, stopping, H5-owned, and
+error/recovery states instead of maintaining a second Boolean inside the button
+driver.
+
+## Deterministic button behavior
+
+For a mechanical active-low or active-high input, require all of the following:
+
+- a stable active interval before one press event;
+- no repeat event until a stable release;
+- a button already held during boot must be released before it can trigger;
+- short/long-press thresholds have an explicit product meaning;
+- queue overflow or rejected intents are logged and recover safely;
+- polling tasks and ISRs stay bounded and never block on network/session work.
+
+Test boot-held, bounce, rapid repeated presses, press during connection, press
+during active audio, press during stop, delayed SDK callbacks, and recovery to
+H5 or waiting state. For a battery product, separately test cold power-on,
+software shutdown/deep sleep, wake, charging/USB behavior, and reset; a passing
+AI toggle does not prove the power path.
+
+Keep debounce and gesture state transitions separable from GPIO/RTOS plumbing
+so host tests can prove boot-held suppression, one event per stable press,
+release re-arming, and the selected rapid-gesture policy. Add a focused runtime
+test for stale or duplicate control intents whenever the runtime performs the
+authoritative state validation.

package/skills/tirtc-esp32-builder/references/reporting.md

@@ -16,13 +16,17 @@ Use [the report template](../assets/report-template.md) and preserve separate `P
 | L6 Sessions | AI, device-call and WeChat VoIP requested flows work; simultaneous capture/playback, AEC/double-talk, stop, timeout and H5 recovery are observed separately |
 | L7 Stability | Requested weak-network, repeated-session, resource, and soak criteria pass |
 
-Run and record the intake assessment before L0, the build assessment with `--project` and the exact artifact SHA-256 at L1, and the HIL assessment only when matching runtime evidence exists. Before assessment, copy final deliverable BIN/ELF files to project-relative `artifacts/` paths and record their actual byte size and SHA-256 in `build_evidence.artifacts[]`; the assessor reopens the file and rejects stale metadata. Missing serial or browser access is a `SKIP` for the affected L2-L7 levels, not an L0/L1 failure.
+Run and record the intake assessment before L0, the build assessment with `--project` and the exact artifact SHA-256 at L1, and the HIL assessment only when matching runtime evidence exists. Follow [firmware-delivery.md](firmware-delivery.md) for artifact location, retention, and mode-transition rules. Record actual byte size and SHA-256 in `build_evidence.artifacts[]`; the assessor reopens the file and rejects stale metadata. Missing serial or browser access is a `SKIP` for the affected L2-L7 levels, not an L0/L1 failure.
 
-Keep `COMPILE_PASS` separate from `BUILD_VERIFIED`. When the compiler succeeds but a required runtime, audio, or video semantic gate fails or is missing, record the compiler result and report the feature and project as blocked. After build assessment, remove `build/` without rebuilding and run `project_portability.py --export`; the source deliverable may retain verified `artifacts/` copies but not a machine-bound build tree. H5 image display is L5 evidence, never an inference from L1.
+Keep `COMPILE_PASS` separate from `BUILD_VERIFIED`. When the compiler succeeds but a required runtime, audio, or video semantic gate fails or is missing, record the compiler result and report the feature and project as blocked. H5 image display is L5 evidence, never an inference from L1.
 
 ## Evidence
 
-Record exact board revision, selected media, Wi-Fi, and binding profiles, toolchain and SDK versions, source/adapter revisions, commands, return codes, firmware size and SHA-256, serial port/chip, sanitized log paths, browser or platform observations, and every unavailable dependency.
+Record exact board revision, selected media, Wi-Fi, and binding profiles,
+toolchain and SDK versions, source/adapter revisions, commands, return codes,
+firmware version, application-BIN SHA-256, descriptor/full ELF SHA-256, serial
+port/chip, sanitized log paths, browser or platform observations, and every
+unavailable dependency. Never conflate the BIN and ELF hashes.
 
 Runtime evidence belongs to one artifact. Label superseded artifacts and keep their observations as history; do not promote them to the current BIN/ELF. For HIL assessment, add the full SHA-256 to `runtime_evidence` and run `hardware_ir.py assess --phase hil --artifact-sha256 <sha> --strict`.
 

package/skills/tirtc-esp32-builder/references/workflow.md

@@ -30,6 +30,9 @@ Use this branch when the user supplies a board model, vendor URL, schematic, BOM
 2. Freeze the user-supplied product contract: selected video profile, audio/stream formats, duplex/AEC policy, supported Wi-Fi credential methods, selected onboarding method, transport staging, output path, and mutation boundary. Use `unknown` where the prompt lacks an answer.
 3. Prefer official schematic/BOM and BSP facts. For a PDF schematic, inspect page labels and net names; prefer an exported netlist, pin CSV, or vendor board definition when available.
 4. Cross-check critical pins, clocks, power enables, reset lines, sensor/codec variants, ESP-IDF version, resource ownership, and onboarding behavior across at least two independent artifacts when possible.
+   For buttons, power keys and enclosure labels, identify the full physical
+   product including carrier/PMIC layers; a working control missing from the
+   baseboard schematic is a variant or evidence gap, not proof that it is absent.
 5. Create the Hardware IR v2. Use `null` for unknown facts and retain contradictory values as an explicit issue instead of selecting one silently. Store concrete board values in the IR/adapter rather than Skill files.
 6. Validate and run the intake assessment. Classify unresolved facts by their next evidence source: source, implementation, build, HIL, or user input. Ask only for `user_blocked` facts that prevent a safe design. SoftAP is optional when another evidenced Wi-Fi credential method is available, keeps credentials outside source, and defines reprovisioning.
 7. When hardware identity, wiring, product contracts, and an evidenced resource plan reach `READY_TO_PORT`, generate the starter and implement the board adapter. Generate a compile-safe adapter by default when remaining uncertainty is implementation-, build-, or HIL-resolvable. Stop at the IR/report only when missing user evidence or an incompatible dependency makes a safe implementation impossible.
@@ -79,6 +82,14 @@ connection handles, pending calls, monotonic deadlines, session generation, and
 H5/AI/CALL/VOIP sequencing. SDK lifecycle changes such as disconnect run in a
 worker/state-machine context, never directly inside an SDK callback.
 
+A separate product-controls adapter owns physical input setup, debounce,
+boot-held suppression and gestures. It queues bounded intents into the stable
+runtime. It never manipulates TiRTC/session state directly or keeps a competing
+session Boolean. Prefer an atomic runtime-owned toggle intent; when only explicit
+start/stop intents exist, follow
+[product-controls.md](product-controls.md) for snapshot mapping and authoritative
+runtime revalidation.
+
 ## Verification loop
 
 Use a bounded loop per layer: diagnose one failing invariant, make the smallest correction, and rerun that layer before moving forward. Change one high-risk variable per HIL comparison. Turn reusable invariants into tests or post-link gates. Stop and report when the remaining failure requires unavailable hardware, credentials, a new SDK binary, a public protocol change, or a user choice.

package/skills/tirtc-esp32-builder/scripts/firmware_identity.py

@@ -0,0 +1,180 @@
+#!/usr/bin/env python3
+"""Inspect the ESP-IDF application descriptor in an application BIN."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import struct
+import sys
+from pathlib import Path
+from typing import Any
+
+
+ESP_IMAGE_MAGIC = 0xE9
+ESP_APP_DESC_MAGIC = 0xABCD5432
+IMAGE_HEADER_SIZE = 24
+SEGMENT_HEADER_SIZE = 8
+APP_DESC_OFFSET = IMAGE_HEADER_SIZE + SEGMENT_HEADER_SIZE
+APP_DESC_REQUIRED_SIZE = 176
+
+
+def sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as stream:
+        for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def descriptor_string(data: bytes, offset: int, size: int, label: str) -> str:
+    raw = data[offset : offset + size]
+    value = raw.split(b"\0", 1)[0]
+    try:
+        decoded = value.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        raise ValueError(f"application descriptor {label} is not UTF-8") from exc
+    if any(ord(character) < 0x20 or ord(character) == 0x7F for character in decoded):
+        raise ValueError(f"application descriptor {label} contains control bytes")
+    return decoded
+
+
+def inspect_firmware(
+    firmware_path: Path,
+    *,
+    elf_path: Path | None = None,
+    expected_version: str | None = None,
+) -> dict[str, Any]:
+    firmware = firmware_path.expanduser().resolve()
+    try:
+        data = firmware.read_bytes()
+    except OSError as exc:
+        raise ValueError(f"cannot read application BIN {firmware}: {exc}") from exc
+
+    minimum_size = APP_DESC_OFFSET + APP_DESC_REQUIRED_SIZE
+    if len(data) < minimum_size:
+        raise ValueError(
+            f"application BIN is truncated: need at least {minimum_size} bytes"
+        )
+    if data[0] != ESP_IMAGE_MAGIC:
+        raise ValueError(
+            f"not an ESP application image: expected magic 0x{ESP_IMAGE_MAGIC:02x}"
+        )
+
+    segment_length = struct.unpack_from("<I", data, IMAGE_HEADER_SIZE + 4)[0]
+    if segment_length < APP_DESC_REQUIRED_SIZE:
+        raise ValueError("first ESP image segment is too small for esp_app_desc_t")
+
+    descriptor = data[APP_DESC_OFFSET : APP_DESC_OFFSET + APP_DESC_REQUIRED_SIZE]
+    descriptor_magic = struct.unpack_from("<I", descriptor, 0)[0]
+    if descriptor_magic != ESP_APP_DESC_MAGIC:
+        raise ValueError(
+            "first ESP image segment does not start with a valid esp_app_desc_t"
+        )
+
+    version = descriptor_string(descriptor, 16, 32, "version")
+    if not version:
+        raise ValueError("application descriptor version is empty")
+    if expected_version is not None and version != expected_version:
+        raise ValueError(
+            f"firmware version mismatch: expected {expected_version!r}, got {version!r}"
+        )
+
+    elf_digest = descriptor[144:176].hex()
+    result: dict[str, Any] = {
+        "firmware_path": str(firmware),
+        "size_bytes": len(data),
+        "bin_sha256": hashlib.sha256(data).hexdigest(),
+        "segment_count": data[1],
+        "project_name": descriptor_string(descriptor, 48, 32, "project_name"),
+        "version": version,
+        "build_time": descriptor_string(descriptor, 80, 16, "time"),
+        "build_date": descriptor_string(descriptor, 96, 16, "date"),
+        "idf_version": descriptor_string(descriptor, 112, 32, "idf_ver"),
+        "app_elf_sha256": elf_digest,
+    }
+
+    if elf_path is not None:
+        elf = elf_path.expanduser().resolve()
+        try:
+            elf_size = elf.stat().st_size
+            actual_elf_digest = sha256_file(elf)
+        except OSError as exc:
+            raise ValueError(f"cannot read ELF {elf}: {exc}") from exc
+        if actual_elf_digest != elf_digest:
+            raise ValueError(
+                "ELF SHA-256 mismatch: application descriptor records "
+                f"{elf_digest}, file is {actual_elf_digest}"
+            )
+        result.update(
+            {
+                "elf_path": str(elf),
+                "elf_size_bytes": elf_size,
+                "elf_sha256": actual_elf_digest,
+            }
+        )
+
+    return result
+
+
+def print_human(result: dict[str, Any]) -> None:
+    fields = (
+        ("firmware", "firmware_path"),
+        ("project", "project_name"),
+        ("version", "version"),
+        ("build", "build_date"),
+        ("time", "build_time"),
+        ("idf", "idf_version"),
+        ("size_bytes", "size_bytes"),
+        ("bin_sha256", "bin_sha256"),
+        ("app_elf_sha256", "app_elf_sha256"),
+        ("elf", "elf_path"),
+        ("elf_size_bytes", "elf_size_bytes"),
+        ("elf_sha256", "elf_sha256"),
+    )
+    for label, key in fields:
+        if key in result:
+            print(f"{label}: {result[key]}")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description=(
+            "inspect version and SHA-256 identity from an ESP-IDF application BIN"
+        )
+    )
+    parser.add_argument("firmware", type=Path, help="ESP-IDF application BIN")
+    parser.add_argument(
+        "--elf",
+        type=Path,
+        help="matching ELF; its SHA-256 must equal app_elf_sha256 in the BIN",
+    )
+    parser.add_argument(
+        "--expect-version",
+        help="fail unless the application descriptor contains this exact version",
+    )
+    parser.add_argument("--json", action="store_true", help="emit JSON")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        result = inspect_firmware(
+            args.firmware,
+            elf_path=args.elf,
+            expected_version=args.expect_version,
+        )
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    if args.json:
+        print(json.dumps(result, indent=2, sort_keys=True))
+    else:
+        print_human(result)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())