Skip to content

feat(#5568): add top-level preflight_check to harness schema - #6009

Open
fullsend-ai-coder[bot] wants to merge 1 commit into
mainfrom
agent/5568-top-level-preflight-check
Open

feat(#5568): add top-level preflight_check to harness schema#6009
fullsend-ai-coder[bot] wants to merge 1 commit into
mainfrom
agent/5568-top-level-preflight-check

Conversation

@fullsend-ai-coder

Copy link
Copy Markdown
Contributor

Summary

  • Adds a top-level preflight_check field to the Harness struct, enabling harness authors to validate host-side dependencies for all scripts (pre_script, post_script, validation_loop) in a single command before sandbox creation
  • Wires the new field into forge resolution (ForgeConfig), base composition (mergeBaseIntoChild, mergeForgeConfigInto), ${VAR} expansion, and ValidateRunnerEnvWith — matching the same infrastructure as the existing validation_loop.preflight_check
  • Preserves backward compatibility: the existing validation_loop.preflight_check remains functional and runs after the top-level check

Design choice

The issue offered two options: a top-level field vs per-script siblings. A top-level field was chosen because pre_script and post_script are flat strings (not structs), so adding per-script siblings would require either breaking the schema or adding awkward pre_script_preflight_check/post_script_preflight_check fields. A single top-level command that validates all dependencies is simpler and more general.

Testing

  • Unit tests for YAML loading (TestLoad_TopLevelPreflightCheck*)
  • Unit tests for ValidateRunnerEnvWith coverage of ${VAR} refs
  • Unit tests for base composition (TestLoadWithBase_LocalBase_TopLevelPreflightCheck*)
  • Unit tests for forge resolution (TestResolveForge_PreflightCheck*)
  • Unit tests for mergeForgeConfigInto (TestMergeForgeConfigInto_TopLevelPreflightCheck*)
  • Integration tests for runAgent execution: pass, fail, timeout, and both-checks-configured scenarios
  • All existing preflight tests continue to pass (backward compatibility)

Closes #5568

Post-script verification

  • Branch is not main/master (agent/5568-top-level-preflight-check)
  • Secret scan passed (gitleaks — 6efbe40026557d24e2643701167e7a53079c57ee..HEAD)
  • PR body secret scan passed (gitleaks — no-git)

@fullsend-ai-coder
fullsend-ai-coder Bot requested a review from a team as a code owner August 7, 2026 13:26
@fullsend-ai-coder fullsend-ai-coder Bot added the ready-for-review Agent PR ready for human review label Aug 7, 2026
@fullsend-ai-review

fullsend-ai-review Bot commented Aug 7, 2026

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 1:27 PM UTC · Completed 1:45 PM UTC

Commit: 576eb95 · View workflow run →

@codecov

codecov Bot commented Aug 7, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@fullsend-ai-review

fullsend-ai-review Bot commented Aug 7, 2026

Copy link
Copy Markdown

Looks good to me

Previous run

Looks good to me

Previous run (2)

Review

Findings

Medium

  • [missing-field-in-reference] docs/guides/user/bring-your-own-agent.md:228 — The "Harness field reference" section does not include the new top-level preflight_check field. This is the primary user-facing field reference, so omitting it means users will not discover the feature through documentation.
    Remediation: Add preflight_check to the "Scripts" section of the harness field reference, near pre_script and post_script.

  • [stale-schema-reference] docs/ADRs/0045-forge-portable-harness-schema.md:471 — The ForgeConfig Go struct definition in the ADR is missing the new PreflightCheck field added by this PR. The actual ForgeConfig struct in internal/harness/forge.go now includes PreflightCheck, but the ADR's code block still shows the old struct without it.
    Remediation: Add PreflightCheck string to the ForgeConfig struct in the Go code block (between PostScript and Policy lines).

  • [stale-field-table] docs/ADRs/0045-forge-portable-harness-schema.md:245 — The "Fields that can appear at both levels" table does not list preflight_check. This PR adds preflight_check as a field that can appear at both the harness top level and inside forge.<platform> blocks, but the table does not reflect this.
    Remediation: Add a row for preflight_check to the "Fields that can appear at both levels" table.

Low

  • [naming-consistency] internal/cli/run.go:750 — The StepFail message for the top-level preflight check ("Preflight dependency check failed") is identical to the validation_loop StepFail message. With two separate preflight checks now running sequentially, operators cannot distinguish which one failed from the StepFail output alone. The StepStart and StepDone messages were properly disambiguated.
    Remediation: Change the top-level StepFail to "Preflight: harness dependency check failed" and the validation_loop StepFail to "Preflight: validation_loop dependency check failed".

  • [stale-schema-example] docs/ADRs/0024-harness-definitions.md:384 — The harness YAML schema reference in ADR 0024 does not include the new preflight_check field. The schema block already includes fields added after the original ADR.
    Remediation: Add preflight_check to the schema block near pre_script/post_script.

  • [stale-run-sequence] docs/guides/dev/cli-internals.md:332 — The Sandbox Lifecycle diagram does not show the top-level preflight_check step. The actual run flow now runs preflight_check after file validation but before sandbox creation.
    Remediation: Add a preflight check step between file validation and EnsureAvailable in the diagram.


Labels: PR adds a new harness schema field and wires its execution through the agent runner.

fullsend-ai-review[bot]

This comment was marked as outdated.

@fullsend-ai-review fullsend-ai-review Bot added requires-manual-review Review requires human judgment component/harness Agent harness, config, and skills loading component/runner Agent runner behavior and lifecycle labels Aug 7, 2026
@waynesun09
waynesun09 force-pushed the agent/5568-top-level-preflight-check branch from 576eb95 to a031486 Compare August 7, 2026 15:10
@fullsend-ai-review

fullsend-ai-review Bot commented Aug 7, 2026

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 3:12 PM UTC · Completed 3:28 PM UTC

Commit: a031486 · View workflow run →

fullsend-ai-review[bot]

This comment was marked as outdated.

@fullsend-ai-review fullsend-ai-review Bot added ready-for-merge All reviewers approved — ready to merge and removed requires-manual-review Review requires human judgment labels Aug 7, 2026
Add a top-level `preflight_check` field to the Harness struct so
harness authors can validate host dependencies for all scripts
(pre_script, post_script, validation_loop) in a single command
before sandbox creation.

Design: a top-level `Harness.PreflightCheck` string field that
runs once at the same execution point as the existing
`validation_loop.preflight_check`. The validation_loop-level
field is preserved for backward compatibility and runs after
the top-level check.

Changes:
- harness.go: add PreflightCheck field to Harness, add
  ValidateRunnerEnvWith coverage for ${VAR} expansion
- forge.go: add PreflightCheck to ForgeConfig, wire into
  mergeForgeConfig for forge-specific overrides
- compose.go: add PreflightCheck to mergeBaseIntoChild and
  mergeForgeConfigInto for base composition
- run.go: wire ${VAR} expansion and preflight execution at
  the same point as the existing validation_loop check

Note: pre-commit could not run in sandbox (network 403).
The post-script runs it authoritatively on the runner.

Closes #5568

Assisted-by: Claude (fix, review), Grok (review)
Signed-off-by: Wayne Sun <gsun@redhat.com>
@waynesun09
waynesun09 force-pushed the agent/5568-top-level-preflight-check branch from a031486 to b87d7f1 Compare August 7, 2026 15:47
@fullsend-ai-review

fullsend-ai-review Bot commented Aug 7, 2026

Copy link
Copy Markdown

🤖 Review · ❌ Terminated · Started 3:48 PM UTC · Ended 4:01 PM UTC

Commit: b87d7f1 · View workflow run →

@github-actions

github-actions Bot commented Aug 7, 2026

Copy link
Copy Markdown

Site preview

Preview: https://b8355628-site.fullsend-ai.workers.dev

Commit: b87d7f13eb8f84a5df41d2888b54c24ab9d0e1d0

@fullsend-ai-review

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 3:48 PM UTC · Completed 4:01 PM UTC

Commit: b87d7f1 · View workflow run →

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

component/harness Agent harness, config, and skills loading component/runner Agent runner behavior and lifecycle ready-for-merge All reviewers approved — ready to merge ready-for-review Agent PR ready for human review

Projects

None yet

Development

Successfully merging this pull request may close these issues.

runner: extend preflight_check to pre_script/post_script (not just validation_loop)

1 participant