insar-management-system-v2/docs/GAMMA_SBAS_RUNTIME_OBSERVATIONS_20260611.md

Gamma SBAS runtime observations - 2026-06-11

1. Interactive display window blocks unattended runs

Observed during run:

run_id: sbas_c65c7486f76e
workflow: SBAS_GAMMA_WORKFLOW
stage: 02_import_lt1_slc.sh
date observed: 2026-06-11

User reported a Gamma/WSL display-style window during execution. The window only had a Close button. After the user clicked Close, the workflow continued.

Runtime checks later showed the same run was still in 02_import_lt1_slc.sh, processing LT-1 scenes with par_LT1_SLC. The first two scenes completed:

20230624 -> completed SLC import
20230726 -> completed SLC import
20230819 -> running at 2026-06-11 11:18 Asia/Shanghai

There was a large delay between the end of 20230726 and the start of 20230819. This is consistent with a blocking interactive display process. The likely trigger is the browse/preview commands in the import step:

disSLC ...
dismph_fft ...

These commands are useful for expert visual inspection, but they are not acceptable as blocking UI windows in a managed background production workflow.

The same window was reported again later in the same run while the import step was still active. This confirms the issue is repeatable and should be treated as a workflow design defect, not a one-off operator/environment event.

For the active run, do not modify the generated shell script in place unless the operator explicitly chooses to skip the remaining interactive preview commands. A targeted intervention is possible only when the active child process is a display command such as disSLC or dismph_fft; terminating par_LT1_SLC or the parent bash process would risk corrupting or interrupting the import product.

2. Current operational decision

The operator changed the decision after the window repeated: stop this run, clear the run records, and audit/fix the production workflow before re-running.

Completed cleanup:

run_id: sbas_c65c7486f76e
processes: stopped
run directory: deleted
system_tasks deleted: 1
system_jobs deleted: 1
catalog products deleted: 0

3. Required follow-up after this run

The fix must preserve expert-command equivalence for calculation commands while removing interactive blocking behavior.

Important distinction:

• disSLC and dismph_fft are expert command-line manual QC/display commands.
• They are not required numerical SBAS calculation steps.
• In a managed backend production workflow they must not open a UI window.
• The system should expose reviewable assets through generated rasters/previews and frontend visualization instead.

Implementation requirements:

1. Keep expert preview/browse products where they are generated by non-interactive raster/export commands.
2. Do not execute expert manual display commands in default backend production.
3. Never require an operator to click Close for a backend job to continue.
4. Add a workflow-level guard that detects display commands likely to open an interactive window.
5. Update run status reporting so the frontend shows the actual executing step instead of leaving 02_import_lt1_slc as PENDING while the WSL process is running.

Candidate code area:

backend/app/services/sbas_insar_production_service.py
  _write_import_lt1_slc_script / 02_import_lt1_slc.sh generation

Related generated commands observed in the current script:

disSLC "${slc}" "${width}" 1 0 - - 1 1 "${SLC_DIR}/${date}.slc.bmp" || true
dismph_fft "${slc}" "${width}" 1 0 - - 1 1 "${SLC_DIR}/${date}.slc_fft.bmp" || true

Implementation decision:

• Remove disSLC and dismph_fft from generated unattended production scripts.
• Keep them in expert-document metadata as manual_qc_tools.
• Add script-write and command-audit guards so future generated scripts fail before execution if blocking display tools are present.
• Keep ras* commands that write explicit output BMP/GeoTIFF preview files; those are batch product-generation commands, not interactive display windows.

4. Acceptance criteria

After the fix:

• A full Gamma SBAS run can complete unattended from the web UI.
• No Gamma display window should require manual close.
• Preview BMP/PNG artifacts are still generated for inspection when feasible.
• The step status file and frontend task status reflect the active step during long-running shell scripts.