Files
dxdesigner-part-replacement/docs/testing/2026-11-06-nonblocking-resources.md
T

16 KiB
Raw Blame History

T2 — nonblocking project resources, 2026-11-06

Scope: R08–R16 and R22 in docs/superpowers/plans/2026-11-06-nonblocking-repair-checklist.md. All changes stay in the shared codex-nonblocking-items worktree. No commit, real CAD/PCB execution, AI call, network send, or user environment-variable change was performed.

Result and production wiring

  • workspace_execution.execute_workspace_projects freezes ordered task IDs, plan hashes, parent phase, deterministic child checkpoint IDs, release flags, and problem-pass completion in workspace-queues/<id>.json. Each project calls the existing supervised task queue separately. A released uncertain A remains blocked with durable uncertainty while B can run. An unproved release pauses the parent. Resume skips blocked A after manual physical reconciliation; it never replays A. All primary projects precede deferred problem passes; paused/running problem passes resume the same child checkpoint.
  • BatchCadRuntime reuses CAD within one project, then closes its complete owned generation before another project starts. Rebuilds still share the existing one-per-project retry budget; changing projects does not replenish it. Old leases retain their original generation.
  • reset_project_after_safe_failure(project, evidence_root, *, job_id=None) requires the current owned close checkpoint and returns a persisted health proof. It binds the exact selected failed job to its current attempt/generation, hashes that attempt record, and checks can_retry_attempt for no mutation. It records a fresh after-release source fingerprint, whether the whole source fingerprint stayed unchanged, an immutable release snapshot/hash, checkpoint hash, and immutable per-job health file. A closed project alone is not a no-write certificate. Callers must require affirmative no-mutation/source/release proof or combine a verified native rollback baseline for that same job.
  • Read provenance is fixed at admission (bom_import and collect_target_inventory). Failed/cancelled CAD reads release all owned workers, CAD, and desktop before raising ReleasedProjectReadError. Proven native read failure uses the same release path without spending a retry or opening another desktop. Execution-provenance native prewrite recovery retains its existing strict source/identity proof and one-shot budget.
  • batch_worker observes the admitted GUI parent PID plus creation time, persists owner-loss evidence, and requests cancellation. Read workers use bounded cooperative cancellation. Owner loss never grants permission to kill a possible write.
  • ProgressWatch tracks worker liveness and business progress separately. Repeated identical stdout/native counts cannot extend the business idle deadline. Unsafe write stalls request safe stop and retain the process. BusinessProgressWatch separately ignores supervisor heartbeats and unchanged state.
  • Every retained worker/runtime/CAD/supervisor wait has an exact owned-process exit observer. Native observers check both root handles and Job descendants. A completed root cannot hide live descendants. Confirmed physical exit ends the wait while uncertainty remains.
  • No-control write sessions retain their handles when orderly shutdown fails. They do not fall through to terminate-capable desktop cleanup. Raw retained CAD owners remain in a live registry, appear in pending resource status, block another CAD launch, and reconcile normally only once every retained owned tree has exited.
  • force_pending_owned_resources(root, *, confirmed=False) is an in-process GUI API. Default/false refuses without action. Explicit true validates live retained handle identities against durable records, writes uncertainty/protection and force intent, then terminates only those exact owners. It supports GUI supervisor Jobs, batch runtimes, and raw retained CAD sessions. Corrupt/reused PID identity and denied protection both prevent termination. Ordinary resource cleanup refuses to force a retained write Job.
  • Unknown/save/license dialogs retain their text and actual buttons. The worker accepts only one-shot requests bound to supervisor batch/attempt, generation, and CAD session token. The desktop re-enumerates and compares the complete dialog fingerprint before an explicit user's selected button is sent. Existing automatic acknowledgement remains restricted to a complete recognized VBScript compilation-error prompt with one permitted OK button. Startup CAD PID ownership is published before GUID binding, so startup prompts can also be handled manually.
  • ui.cad_dialog_operations.show_cad_dialogs(window) displays the active project, original prompt text, and explicit original button choices. Root integration repurposes the existing resource cleanup button while the supervisor reports a blocking prompt. No global input, desktop switching, save decision, license decision, or automatic unknown-dialog click was introduced.
  • Persistent/process-local discovery caches refresh metadata-only differences while hashing every file's content on lookup. File replacement, changed content, unreadable files, changed inventories, and unknown identities remain misses. Identity comparisons include optional actual Part Label/Cell metadata and preserve None versus an empty string. A verified reader-release hook runs before the after-discovery fingerprint to release file locks.

Red/green evidence

Commands used Python 3.12 and pytest with unique short F:/dx-nb-res-* basetemp paths and F:/dx-nb-res-cache; no test output directories are in the repository.

Regression introduced first Observed red Observed green
Initial resource boundaries 9 failures: CAD identity skipped, legacy CAD released without identity, a released label bypassed evidence, metadata-only changes reread, missing exit observer/business clock/read provenance/reset/manual action Initial set expanded to 14 passing cases
Read generation cleanup and project switch Unsupported read-only session flag and old CAD reused for another project Read failure closes one generation without retry; next project starts only after previous CAD closes
Owner loss and worker exception wait Missing recovery module and missing resolved observer Verified parent identity evidence; unsafe worker exception resolves on owned exit
Frozen workspace queue 5 missing-module failures Ordered A/B isolation, no release proof holds B, exact resume IDs and stale hashes rejected
Manual transport/UI Missing one-shot consumer and missing UI module Generation/token mismatch rejected, one action only; actual prompt text shown, no action until button click
Failed cleanup ownership CAD reference dropped and desktop closed after an active write owner cleanup failure CAD/desktop retained; Job descendants keep exit observer false
Native read no replay Read-only native failure created another session instead of raising released read error One generation released, no retry budget spent
Identical heartbeat progress Both stdout and native repeated count frames hid the business deadline Both request safe stop then wait indefinitely for a possible write
Finished supervisor label finished skipped an original live process Live original remains pending
Crashed supervisor with harmless 6-second child Existing five-second descendant grace automatically killed the possible-write Job (forced_termination=True) Child exits naturally; forced_termination=False, durable uncertainty remains, resources released
No-control possible write Harmless owned Python sleep process killed on failed Quit Process remains alive and retained; only explicit confirmed force releases it
Explicit retained Job force API absent No confirmation, mismatched creation time and denied protection all refuse to kill; exact protected confirmed Job is terminated
Health/metadata proof Reset returned a boolean; actual metadata unknown/empty compared equal Current attempt/source/release hashes are persisted; unknown differs from empty
Paused deferred problem pass Resume skipped paused project and falsely marked parent finished Same child checkpoint resumes in the persisted problems phase
Raw owner natural exit Exited raw session remained permanently pending All owned trees observed exited; ordinary cleanup releases handles, retains uncertainty, never force-kills
Completed CAD root with active descendants/repeated force Root exit permitted desktop cleanup; repeated force returned early from root PID alone Tree-level proof is required; explicit force still reaches the retained Job

Targeted verification performed

  • Initial necessary resource regression set (test_batch_runtime, test_batch_supervisor, test_isolated_cad, test_isolated_desktop, test_cad_dialogs, test_discovery_cache, test_persistent_discovery_cache, test_worker_monitor): 218 passed, 3 failed. Two old assertions assumed CAD reuse between distinct projects; those assertions now verify required serial project isolation while retaining same-project reuse. The third was a native harmless modal probe's five-second transient timeout. Its evidence showed the recognized compilation prompt and recorded acknowledgement; the exact isolated rerun passed 1/1 in 1.48 seconds. No production workaround or timeout weakening was added.
  • After the project-lifecycle assertions: runtime + initial new resource/workspace/Qt tests passed 59/59.
  • Native read resource change: native/resource/runtime focused set passed 55/55.
  • Business/liveness separation: resources + worker monitor passed 55/55.
  • Affected integration set (resources, workspace, Qt, supervisor, runtime integration, native reader and project discovery): 93 passed, 1 failed. The failure was a previously supported injected runtime=object() without the new release hook. Root changed the caller to require a callable hook. The exact failed discovery case then passed 1/1; the 93-test set was not repeated.
  • Resources/workspace/Qt/runtime/isolated-CAD after no-control ownership and proof changes passed 106/106. Additional real harmless raw/runtime force variants passed 2/2.
  • Final affected safety set (test_nonblocking_resources, test_workspace_execution, test_cad_dialog_operations, test_batch_runtime, test_isolated_cad, test_batch_supervisor, test_safe_user_stop): 150 passed in 109.07 seconds. This includes all final retained-owner/descendant/force changes. All 12 edited/new resource modules parse successfully; git diff --check passes. No broad repository suite is claimed.

Limits and review boundaries

Native behavior was verified through owned disposable Python processes, Windows Jobs/desktops, and a harmless modal dialog. Real Viewdraw/COM/CAD saving, actual license dialogs, and production design files were not exercised. An unverified or legacy CAD record without a PID creation-time identity remains pending rather than guessing ownership. After restart, reconciliation observes disappearance only; the force API never opens arbitrary PIDs or attaches to a foreign application. An unavailable source fingerprint fails closed. Business uncertainty is never cleared by resource release or force.

Root owns task-queue admission, receipts, rollback/native baselines, service/UI entry wiring, and integration acceptance. This T2 record does not claim those separate caller changes solely from helper availability; their own tests/review must verify the real admission path.

Independent review fixes: complete owned write trees

The read-only review reproduced four additional ownership gaps, then the parent explicitly assigned their implementation to the reviewer. No real CAD/PCB or AI was used.

  • Successful Quit now checks every owned CAD/helper/worker tree before desktop cleanup. Root exit code zero cannot authorize killing surviving descendants. Runtime cleanup retains the CAD owner when any retained Quit-helper or desktop process remains.
  • Unsafe monitor exceptions, unsuccessful resolution observers, normal root completion with live children, and a stalled write without an interactive controller retain the exact process/Job handles. RETAINED_WORKERS exposes these owners through pending-resource status and explicit confirmed force. Force verifies creation identity against durable evidence and protects uncertainty before terminating. Ordinary cleanup only closes trees observed exited.
  • A durable retained-worker-<token>.json record continues to block after registry/process restart. Without the original Job handle, root PID disappearance cannot prove descendant exit and cannot authorize force. Natural exit and explicit force in the owning process write a released tree proof; uncertainty is retained.
  • Reconciliation consults both retained and active supervisor handles, so a finished/root-exited journal cannot hide a live owned Job.
  • Every supervised worker uses StopControl, including noninteractive callers. Its finalization observes retained write owners before process exit can close Windows kill-on-close Jobs. A protected active supervisor is reachable through the existing explicit service force API: the API validates identity, durably records force-request.json, and signals its owning loop; the loop performs protected termination. It does not race the owner's handle cleanup or bypass the supervisor lease for direct termination.
  • Diagnostic exports now include these two narrowly named sidecars; component-scope/input tables remain excluded.

Focused evidence

tests/v1_1/test_retained_write_owners.py contains 18 cases. The first six ownership cases failed before their fixes. Additional red cases covered noninteractive worker lifetime, active owner reconciliation, resolution-error finalization, restart protection, and a no-controller business stall. Tests use mocked CAD boundaries and real harmless Python children, Windows Jobs, and private desktops.

The necessary affected suite was run once:

python -m pytest tests/v1_1/test_retained_write_owners.py tests/v1_1/test_isolated_cad.py tests/v1_1/test_batch_runtime.py tests/v1_1/test_batch_supervisor.py tests/trial_task_center/test_worker_monitor.py -q --basetemp=F:/dx-review-resource-affected -o cache_dir=F:/dx-review-owner-cache

Result: 136 passed, 1 failed in 65.62 seconds. The new natural-exit test incorrectly expected Job accounting to reach zero immediately when its root handle became signaled. The assertion was corrected to wait for actual full-tree exit. The exact natural/force variants then passed 2/2 (-k retained_native_worker, F:/dx-review-owner-natural-final); no production timeout or ownership guard was weakened and the affected suite was not repeated.

Afterward, the real noninteractive worker lifetime/active-force variants passed 2/2 (-k noninteractive_worker, F:/dx-review-owner-supervisor-force): a natural child wrote its completion marker, while the explicit-force variant retained it until the separate service call requested force and returned user_forced_stop with uncertainty evidence.

The final narrow previous-regression plus no-controller-stall command passed 9/9:

python -m pytest tests/v1_1/test_retained_write_owners.py tests/v1_1/test_nonblocking_resources.py -q -k 'unsafe_stall_without or unsafe_worker_exception_wait or no_control or force_pending or repeat_explicit_force or owned_exit_observer' --basetemp=F:/dx-review-owner-stall-green -o cache_dir=F:/dx-review-owner-cache

Diagnostic sidecar inclusion was red first, then test_diagnostics_bundle.py passed 9/9 (F:/dx-review-owner-diagnostic-green). Production modules parse and git diff --check passes. Counts overlap and are not cumulative. The earlier 150-case resource suite and the broad repository suite were not rerun.