Files
cbb-refresh-verify-795/docs/releases/2026-10-26-icdb-emergency-hotfix.md
T

3.9 KiB

0.2.1 — PCB / iCDB emergency safety fix

Superseded by 0.2.2 after local Mentor testing found the already-verified Forward Annotation defect. See local validation and audit.

Base: 11a2b2e (r4-stability-20260929). This patch addresses confirmed unsafe code paths. It does not establish the cause of a particular field incident and does not repair an already damaged PCB/database.

Changes

  • Preserve database/cdbsvr/sAddress.adr. A TCP timeout is not evidence that its owner is dead. Any existing advertisement (live, unreachable or invalid) blocks automatic Verify until the native session is reviewed.
  • Block a new Verify while any Expedition PCB session is already running, before changing project configuration or attaching to shared COM objects.
  • Do not auto-confirm design-lock overrides or choose a database restoration. Record DATABASE_RECOVERY_REQUIRED without clicking the prompt.
  • Release Python COM references before starting the save helper; release the helper's document/integration references before app.Quit.
  • Observe PCB/launcher/Library Manager exit. Neither a cleanup request nor Save/Close markers alone count as process release. A surviving iCDB address also prevents success.
  • On timeout or failure, stop automation clients without killing the native PCB/iCDB process tree. The Job Object no longer kills native descendants when its handle closes. Library Manager shutdown requests no longer fall back to force termination.
  • Stop the batch on safe_to_continue=False, including unexpected exceptions. Preserve available evidence backups on failure. Record retained processes, the private desktop and project in recovery-required.json; the UI points the operator to the recovery evidence.

Operational consequences

The normal path still performs Project Integration and saves through Mentor. It is not a read-only PCB check. The adapter can also align the CentralLibrary entry in PCB/pcb.prj, preserving its original in the evidence directory.

A failure can deliberately leave a native session alive on the private desktop. This avoids interrupting a database write; it is reported as a failure, never as successful release. Review the recorded desktop/PIDs with the maintainer before closing/recovering that session. Do not delete the address/lock files merely because a connection probe timed out. The presence of an old address may require manual Mentor recovery even when no local PCB process remains.

Existing partial backups exclude volatile database files and network runs may skip them; they are not a complete database rollback. Before field testing, use a consistent, isolated copy made after the original native session closes. Opening a copied database can itself cause Mentor to report a moved/copied DB.

Validation

The incident regression suite covers address preservation, ownership checks, recovery prompts without clicks, COM reference lifetime, retained PCB/iCDB state, supervisor rejection of false PASS, evidence retention and batch stopping. A real Windows Job Object test uses harmless Python processes to check that automation abort/handle closure does not terminate a native-like child.

Run python -m pytest -q and python -m compileall -q src tests. Packaging uses packaging/Build-CbbRefreshVerify.ps1, including its frozen UI smoke check. These checks do not validate recovery of the user's affected production PCB.

Validation completed on Windows 11 / Python 3.12.10:

  • Full suite: 354 passed (including 18 incident regression cases).
  • Python compilation and Git whitespace checks passed.
  • The 32-bit cscript host compiled a non-executing wrapper of the save helper successfully; this checks syntax without connecting to Mentor.
  • PyInstaller 6.22.3 build and frozen UI creation/clean-shutdown smoke passed.

Live Mentor verification and damaged-database recovery remain unvalidated. The package has not been deployed to production or tested on Windows 10.