Files
cbb-refresh-verify-795/docs/superpowers/plans/2026-09-20-bridge-execution-and-unc.md
T
阿白叔 11a2b2e46e Import CBB refresh verify r4 stability baseline
Preserve tested Verify source, authoritative READY checks, bounded bridge retries, diagnostics and failure-only reporting. Include 336-test suite and packaging assets; exclude live Mentor samples, field logs, backups and distributions.
2026-09-29 15:05:20 +08:00

11 KiB

CBB Bridge Execution and UNC Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Replace fragile popup/title/timestamp decisions with a confirmed dialog state machine, structured PCB COM execution bridge, authoritative post-Verify status check, and bounded UNC path handling.

Architecture: A pure Python dialog state machine decides and confirms popup transitions while a Win32 adapter performs scoped window actions. A separate PCB bridge process owns Expedition COM and emits JSONL events; the parent owns the only inactivity deadline. LibraryPathLease maps UNC shares temporarily and supplies a stable Mentor path without recursively fingerprinting the network tree.

Tech Stack: Python 3.12, pytest, pywin32, ctypes/WNet, 32-bit Mentor COM/VBScript licensing helper, PyInstaller.

Spec: docs/superpowers/specs/2026-09-20-bridge-execution-and-unc-design.md

Global Constraints

  • Never inject mouse/keyboard input or switch the user's desktop.
  • Never click an unknown dialog automatically.
  • Never call private VerifyReuseBlock or UnVerifyReuseBlock mutation exports.
  • A failed CBB is logged and skipped; it does not abort the batch.
  • PASS requires a post-close IsVerifiedReuseBlock == READY response.
  • Temporary network mappings never store credentials or remove user mappings.

Task 1: Confirmed Dialog State Machine

Files:

  • Create: src/cbb_refresh_verify/dialog_supervisor.py
  • Modify: src/cbb_refresh_verify/mentor_adapter.py
  • Test: tests/test_dialog_supervisor.py

Interfaces:

  • Produces: DialogSnapshot, DialogDecision, DialogPollResult, DialogSupervisor.poll().

  • Consumes: Win32 observations supplied by an adapter; no Win32 calls in the pure state machine.

  • Step 1: Write failing tests for popup confirmation and safety

def test_click_is_not_resolved_until_dialog_disappears():
    backend = FakeDialogs([license_dialog(), license_dialog(), []])
    supervisor = DialogSupervisor(backend, retry_seconds=0, max_attempts=3)
    assert supervisor.poll().action_sent
    assert not supervisor.poll().resolved
    assert supervisor.poll().resolved

def test_stuck_dialog_fails_after_bounded_retries():
    backend = FakeDialogs([license_dialog()] * 4)
    supervisor = DialogSupervisor(backend, retry_seconds=0, max_attempts=2)
    supervisor.poll(); supervisor.poll()
    assert supervisor.poll().error_code == "DIALOG_STUCK"

def test_unknown_dialog_is_recorded_but_not_clicked():
    backend = FakeDialogs([[dialog(text="Unrecognized destructive prompt")]])
    result = DialogSupervisor(backend).poll()
    assert result.error_code == "UNKNOWN_DIALOG"
    assert backend.actions == []

def test_save_error_is_fatal_even_with_ok_button():
    result = DialogSupervisor(FakeDialogs([[save_error_dialog()]])).poll()
    assert result.error_code == "SAVE_REUSABLE_BLOCK_FAILED"
  • Step 2: Run the tests and verify RED

Run: python -m pytest -q tests/test_dialog_supervisor.py

Expected: collection/import failure because dialog_supervisor does not exist.

  • Step 3: Implement the minimal state machine and Win32 adapter

Implement immutable snapshots with window/PID/control state, fatal classification before generic affirmative classification, pending-action tracking by (hwnd, signature), disappearance confirmation, finite retries, and structured error codes. Win32 enumeration callbacks append observations and explicitly return True; the adapter scopes enumeration to the private desktop and supplied process IDs.

  • Step 4: Integrate compatibility wrapper and verify GREEN

Keep handle_known_dialogs() as a thin compatibility wrapper while run_verify() uses the persistent supervisor instance. Run the targeted test plus existing integration tests.

Run: python -m pytest -q tests/test_dialog_supervisor.py tests/test_integration.py

Expected: all pass.

Task 2: PCB COM Execution Bridge and Single Deadline

Files:

  • Create: src/cbb_refresh_verify/pcb_bridge.py
  • Modify: src/cbb_refresh_verify/application.py
  • Modify: src/cbb_refresh_verify/mentor_adapter.py
  • Modify: src/cbb_refresh_verify/verify_runner.py
  • Test: tests/test_pcb_bridge.py
  • Test: tests/test_verify_runner.py

Interfaces:

  • Produces: PcbBridge.run(job, emit, com_provider, save_runner) and hidden CLI --pcb-bridge <request.json>.

  • Consumes: documented MGCPCB.Application, IMGCPCBProjectIntegration, document save/close APIs, and existing 32-bit licensing helper.

  • Step 1: Write failing bridge state-machine tests

def test_bridge_rejects_wrong_document_before_actions():
    result = run_bridge(job(), com_provider=wrong_document_provider())
    assert result["status"] == "FAIL"
    assert result["error_code"] == "PCB_IDENTITY_MISMATCH"
    assert no_integration_actions(result)

def test_bridge_runs_required_actions_and_requires_post_save_sync():
    provider = staged_provider([required_states(), synchronized_states()])
    result = run_bridge(job(), com_provider=provider, save_runner=successful_save)
    assert result["status"] == "PASS"
    assert provider.actions == ["ForwardAnnotate"]

def test_fatal_dialog_overrides_save_markers():
    assert finalize_result(save_markers=SUCCESS_MARKERS,
                           fatal_dialog="SAVE_REUSABLE_BLOCK_FAILED")["status"] == "FAIL"
  • Step 2: Run targeted tests and verify RED

Run: python -m pytest -q tests/test_pcb_bridge.py tests/test_verify_runner.py

Expected: missing bridge API and missing fatal-result precedence failures.

  • Step 3: Move COM workflow behind the bridge protocol

Remove the exact Expedition title gate. The bridge polls COM directly, verifies document/project identity before action, emits only changed snapshots, performs one allowed Required action at a time, validates/saves/closes, and writes a structured outcome. The worker has no independent inactivity deadline.

  • Step 4: Make the parent the sole deadline owner

run_verify() refreshes its deadline for new bridge events and confirmed dialog transitions. Repeated snapshots do not refresh. Timeout kills the Job Object and returns a safe per-item TIMEOUT.

  • Step 5: Verify targeted tests GREEN

Run: python -m pytest -q tests/test_pcb_bridge.py tests/test_verify_runner.py tests/test_integration.py

Expected: all pass.

Task 3: Authoritative Post-Verify Decision

Files:

  • Modify: src/cbb_refresh_verify/status_bridge.py
  • Modify: src/cbb_refresh_verify/verify_runner.py
  • Modify: src/cbb_refresh_verify/ui/main_window.py
  • Test: tests/test_status_bridge.py
  • Test: tests/test_verify_runner.py
  • Test: tests/test_ui.py

Interfaces:

  • Produces: correlated bridge responses containing request ID, block name, resolved LMC path, and source.

  • Consumes: existing StatusBridgeClient/Server and post-close CBB identity.

  • Step 1: Write failing correlation and final-state tests

def test_bridge_rejects_mismatched_response_identity():
    with pytest.raises(BridgeResponseError):
        parse_bridge_response(response_for("OTHER"), expected_block="TARGET")

def test_save_success_with_pending_post_status_is_fail():
    result = finalize_verify(execution_pass(), BridgeResult("PENDING", "IsVerifiedReuseBlock"))
    assert result.status == "FAIL"
  • Step 2: Verify RED, implement correlation and post-check, verify GREEN

Run RED then GREEN: python -m pytest -q tests/test_status_bridge.py tests/test_verify_runner.py tests/test_ui.py

The UI marks a row Ready only after the final bridge response is READY. A bridge error remains visible and selectable for a later retry; it is never promoted from Cert files.

Task 4: UNC Path Lease and Bounded Network Scan

Files:

  • Create: src/cbb_refresh_verify/network_path.py
  • Modify: src/cbb_refresh_verify/batch_status.py
  • Modify: src/cbb_refresh_verify/library_reader.py
  • Modify: src/cbb_refresh_verify/ui/main_window.py
  • Test: tests/test_network_path.py
  • Test: tests/test_batch_status.py
  • Test: tests/test_library_reader.py

Interfaces:

  • Produces: LibraryPathLease.acquire(path), .mentor_path, .display_path, .close().

  • Consumes: injected WNet backend in tests and Windows WNet API in production.

  • Step 1: Write failing lease and no-recursion tests

def test_unc_uses_existing_mapping_without_releasing_it():
    backend = FakeWNet(existing={"Y:": r"\\server\share"})
    with LibraryPathLease.acquire(r"\\server\share\lib\mentor_lib.lmc", backend=backend) as lease:
        assert lease.mentor_path == Path(r"Y:\lib\mentor_lib.lmc")
    assert backend.cancelled == []

def test_created_mapping_is_released():
    backend = FakeWNet()
    lease = LibraryPathLease.acquire(r"\\server\share\lib\mentor_lib.lmc", backend=backend)
    lease.close()
    assert backend.cancelled == [lease.drive]

def test_fingerprint_does_not_walk_cbb_descendants(tmp_path, monkeypatch):
    # A descendant scandir raises; the lightweight snapshot must still finish.
    assert fingerprint_library(make_library(tmp_path)).sha256
  • Step 2: Verify RED, implement lease and lightweight fingerprint, verify GREEN

Replace recursive _fingerprint_tree() with LMC metadata plus sorted top-level CBB names and top-level metadata. Pass the leased mentor_path consistently to listing, bridge status, preflight and Verify.

Run: python -m pytest -q tests/test_network_path.py tests/test_batch_status.py tests/test_library_reader.py tests/test_ui.py

Expected: all pass and no descendant traversal.

Task 5: Packaging, Regression, and Static Safety Verification

Files:

  • Modify: packaging/CbbRefreshVerify.spec
  • Modify: README.md
  • Modify: tools/status_bridge/README.md
  • Test: tests/test_packaging.py
  • Test: tests/test_packaging_status_bridge.py
  • Test: tests/test_safety.py

Interfaces:

  • Consumes: all new modules and bridge entry points.

  • Produces: one updated dist-optimized/CbbRefreshVerify-Background and archive.

  • Step 1: Add packaging and safety tests, verify RED

Assert the frozen app contains the status bridge, PCB bridge entry point, VBS helper and icon; assert production source has no fixed Expedition title gate and no callback whose return value is list.append().

  • Step 2: Update packaging and documentation, verify GREEN

Run: python -m pytest -q

Expected: complete suite passes with zero failures.

  • Step 3: Build and smoke-test without running Mentor Verify

Run: powershell -ExecutionPolicy Bypass -File packaging/Build-CbbRefreshVerify.ps1 -OutputDirectory dist-optimized

Run: dist-optimized/CbbRefreshVerify-Background/CbbRefreshVerify.exe --smoke-test

Expected: build exit 0, smoke exit 0, no Mentor/PCB process started.

  • Step 4: Retain only the latest package and report limitations

Keep the latest application directory, archive, and user-supplied diagnostic archives/logs. Do not delete user evidence. Report that real Mentor validation remains a one-CBB acceptance step on the work machine.