Logging & Troubleshooting

Logging & diagnostics

STAR keeps the console quiet and clean by default:

Console (stdout): high-level phase milestones and concise, actionable errors only.
Log file: every run writes a full, verbose diagnostic log to ~/.bright-agent/logs/run-<timestamp>.log. The console prints the exact path at startup. Share this file with Bright support if you hit an issue.
Secret redaction: tokens and credentials (BRIGHT_TOKEN, REPO_ACCESS_TOKEN, OPENAI_API_KEY, INFERENCE_TOKEN, Authorization/Bearer/Set-Cookie values) are redacted from all log output, including the log file.
BRIGHT_DEBUG=1: mirrors the full diagnostic log to the console — useful for live debugging in CI. Set it as an environment variable on the run step.

Usage dumping (cost & token analysis)

For offline cost and token-usage analysis, STAR can persist every raw LLM request/response turn to disk. This is off by default — enable it only for debugging spend, tuning prompts, or auditing model behavior, not for normal runs.

Enable: set BRIGHT_DUMP_TURNS to a truthy value (1, true, yes, or on).
Where it writes: <BRIGHT_DUMP_DIR>/<run-uuid>/<NN-label>/turns.jsonl — each run gets its own UUID subdirectory (default base: <cwd>/.tmp), and each prompt conversation lands in its own indexed subfolder.
What it contains: raw request/response turns in JSON Lines format, for offline token/cost analysis per phase and model. At runtime, STAR also prints a per-phase and total token report to the log (the [Tokens] lines).

Collect it in CI (GitHub Actions example):

- name: Run Bright Agent
  env:
    BRIGHT_DUMP_TURNS: "1"
    BRIGHT_DUMP_DIR: "${{ runner.temp }}/bright-dumps"
  run: ./bright-agent

- name: Upload LLM turn dumps
  if: always()
  uses: actions/upload-artifact@v4
  with:
    name: bright-llm-turns
    path: ${{ runner.temp }}/bright-dumps

Common issues

The scan can't reach my app on localhost (CircleCI/GitLab).
Some CI executors run Docker on a separate host from the job, so a container started by STAR isn't reachable on localhost. On CircleCI use the machine executor, not docker with setup_remote_docker. On GitLab use a runner that runs Docker on its own host, or a docker executor with docker-in-docker configured. See Prerequisites.

The binary got committed into my fix PR.
STAR commits with git add -A. Always download the binary (and any SARIF file) outside the checkout — e.g. the runner's temp directory — as shown in every CI template.

A run can't finish because the app needs a value STAR can't guess.
STAR posts a PR comment explaining what's missing. Reply with /bright-agent <guidance> to steer the next run — see Comment Steering.

Fix commits don't trigger my other CI workflows.
This is a platform anti-recursion rule, not a STAR limitation: commits/PRs made with GITHUB_TOKEN (GitHub) or System.AccessToken (Azure DevOps) don't trigger other pipelines. Use a personal access token as REPO_ACCESS_TOKEN if you need the fix push to run your CI.

A run stopped partway through in CI.
STAR watches your CI job's timeout (BRIGHT_CI_TIMEOUT_MINUTES, auto-detected on GitHub Actions) and saves progress to BRIGHT_STAR.md before the runner is killed, with BRIGHT_TIMEOUT_MARGIN_MINUTES of headroom (default 3 minutes). The next run picks up from that saved state instead of starting over. See Configuration.

A build fails with an out-of-space error.
STAR fails fast with a clear message when free disk drops below MIN_FREE_DISK_MB (default 2048 MB) after reclaiming unused Docker artifacts, instead of crashing mid-build with ENOSPC. Free up runner disk or raise the runner's disk size.

I need to validate my setup before a real run.
Set BRIGHT_PREFLIGHT_ONLY=1 to run STAR's local preflight, which checks core configuration and access tokens without starting a scan.

Still stuck? Send the redacted log from ~/.bright-agent/logs/ to Bright support.