truf-server/openspec/changes/stabilize-gitlab-trufflehog-lifecycle/proposal.md

Why

Recent GitLab repository scans produced 12 exit-code-1 outcomes without a fatal diagnostic or finished scanning marker. All were treated as non-retryable terminal failures after one attempt, leaving the same process-lifecycle coverage gap previously observed and corrected for Docker scans.

What Changes

• Run GitLab TruffleHog Git scans without TruffleHog's redundant embedded overseer while retaining external supervision, scan-slot control, timeout enforcement, and Windows Job containment.
• Require the normal completion marker before treating a GitLab scan process as complete.
• Classify incomplete or unexplained GitLab process exits as retryable through the existing three-attempt target policy.
• Preserve findings emitted before an incomplete exit.
• Run a GitLab-only canary before replaying a bounded exact-signature historical batch.
• Keep GitHub, package Git, and other Git scan behavior unchanged.

Capabilities

New Capabilities

• gitlab-scan-lifecycle: Defines external lifecycle ownership, explicit completion, bounded retry, and controlled replay for GitLab repository scans.

Modified Capabilities

None.

Impact

• Affects GitLab command construction and TruffleHog diagnostic disposition in app/scanner.py and source plumbing in app/console_runner.py.
• Adds focused scanner and queue-policy regression coverage.
• Does not change GitLab discovery requests, non-GitLab commands, detector selection, keychecks, or the installed TruffleHog binary.