This tool serves the full rule text: it is meant for the local agent
    driving the audit, which needs the rules to apply them. Nothing else
    in this package returns rule body text.
    

    assistant/model/repo_name/repo_commit/started are supplied by the
    calling agent; tool_version defaults to the installed package version
    if omitted; environment is optional free-form metadata. repo_dir is
    the path to the repository being audited, on disk; it is optional,
    but file_issues needs it to detect the GitHub repository to file
    against, unless a repo is given explicitly on that call instead.
    Calling this twice without finishing the first run (via
    render_report) is an error, since it would silently discard whatever
    domain results have already been recorded; pass replace=True to
    explicitly discard the in-progress run and start over.
    

    If the ENGINEERING_AUDIT_CONFIG environment variable names a path to
    a valid AuditConfig JSON file, it is loaded immediately (the
    documented headless/CI path); an invalid or unreadable file is a
    loud error, never a silently-applied default. Otherwise this starts
    the interactive localhost configuration page and returns its URL for
    the agent to show the user.
    

    Requires start_config to have been called first. In preset mode the
    configuration is already known and is returned immediately. In
    interactive mode this blocks for up to timeout_s seconds waiting for
    the user to submit the configuration page; on timeout it raises a
    clear error rather than proceeding with a default configuration the
    user never actually chose. Call it again (the user's submission is
    still awaited) rather than treating a timeout as a green light.
    

    The payload itself is pydantic-validated by DomainResult (finding and
    verdict consistency, could-not-run reason, could-not-evaluate notes).
    On top of that: the domain must be one of the domains selected for
    this run, and a completed result must carry a verdict for every rule
    the domain defines; a completed result missing a verdict raises
    IncompleteResultError listing exactly which rule ids are missing, so
    the agent can fix and resubmit rather than a skipped rule silently
    passing. Re-recording an already-recorded domain requires
    replace=True, to guard against an accidental overwrite.
    

    Requires config.issue_mode == "github": if the user chose in-report
    delivery instead, this raises rather than filing issues nobody asked
    for. Requires at least one recorded domain result.

    confirm=False (the default) NEVER files anything and never invokes
    gh at all: it returns a preview {repo, count, titles, instruction}
    so the calling agent can show the user exactly what is about to be
    filed on their repository, and get explicit agreement, before a
    single issue goes out. Filing on someone's repo is outward-facing;
    this confirmation step is mandatory, not decorative.

    confirm=True files one issue per finding that has not already been
    filed (a finding whose rule_id is already in this run's filed set is
    skipped, so retrying after a partial failure does not double-file
    the ones that succeeded). The target repository is `repo` if given,
    otherwise detected from the audited repository directory recorded
    by begin_run's repo_dir. If any issue fails to file, filing stops
    immediately and the error lists exactly which rule ids were filed
    (with their URLs) and which were not, so a retry knows where to
    resume.
    

    Requires a resolved configuration. There is nothing to send unless
    config.feedback_text was set on the configuration page, or the
    calling agent supplies extra_text; if neither is present this
    raises rather than filing an empty, pointless issue.

    The feedback body always carries the free text plus a run-metadata
    section (tool version, rules pack, assistant, model, repository,
    timestamps), and then each telemetry section the user consented to
    on the configuration page (coverage totals, findings rollup by
    severity/domain id, self-assessment, environment); an unconsented
    section is left out entirely. Finding text itself is never
    included, only counts.

    Files a labelled issue on the tool author's feedback repository via
    gh. If gh is unavailable or filing fails for any reason, the
    feedback is never lost: this returns a mailto fallback instead,
    with the same body, so the agent can offer to open the user's mail
    client or hand over the text to paste in manually.
    

    Requires a resolved configuration. Sets meta.finished to the given
    ISO timestamp, renders the deterministic HTML report (which itself
    refuses to render an incomplete run: a selected domain with no
    recorded result, or a completed result missing a rule verdict, raises
    rather than producing a report that looks clean over a gap), and
    writes both report.html and run-state.json to the run's output
    directory. Any issue URLs filed this run via file_issues, and any
    feedback issue filed via submit_feedback, are carried on the
    RunState itself, so the written run-state.json is self-sufficient:
    it (and its schema_version) can be handed to
    engineering-audit-render later to re-render the same report without
    this server, this run tracker, or either URL, still in memory.