Add `--timeout` flag to `specterqa run`

[SyncTekLLC]

Currently there is no global timeout for a test run. Add a --timeout flag (in seconds) that hard-stops the run if exceeded.

Default: 300s

Requirements:

• The flag should integrate with the existing budget enforcement in ghostqa run
• When the timeout is reached, the run should exit gracefully with a clear message indicating it was stopped due to timeout
• Exit code should be non-zero (distinct from budget-exceeded)

Example:

ghostqa run product.yaml --timeout 120

This is a good starter issue — the CLI argument parsing is in ghostqa/cli.py and the run loop is in ghostqa/runner.py.

[SyncTekLLC]

Thanks for filing this — a --timeout flag is a great addition and we'd love to see it land.

Status: Accepted and on our roadmap. This is tagged good first issue if anyone wants to pick it up.

Implementation pointers:

• CLI argument parsing is in specterqa/cli.py (note: package was renamed from ghostqa to specterqa)
• The run loop in specterqa/runner.py is where the timeout enforcement should go
• Use signal.alarm() or a threading timer for the hard-stop — make sure it exits gracefully with a clear message
• Exit code should be distinct from budget-exceeded (e.g., exit code 2 for timeout vs 3 for budget)

Contributions welcome — feel free to open a PR and we'll review promptly.