Summary

A run whose embedded engine launches but never produces a first session event
is currently only caught by the overall per-task turn timeout (timeout_seconds).
Because that timeout must be sized for the slowest legitimate full turn, a
session-start hang can block for many minutes (or hours) and surfaces as the
generic session.idle: context deadline exceeded. This adds an opt-in
time-to-first-event watchdog (first_event_timeout_seconds) that aborts such
a wedge in seconds with a distinct, actionable error, while never false-aborting a
slow-but-live first turn.

Related issue

Closes #320

Agent handoff

• Scope: internal/execution (engine + collector), internal/models (config),
  internal/orchestration (wiring), plus JSON schema + docs. No behavior change
  unless first_event_timeout_seconds is set (default 0 = disabled).
• Key files changed:
  • internal/execution/session_events_collector.go — FirstEvent() channel,
    closed on the first event of any type.
  • internal/execution/copilot.go — arms a first-event timer before
    SendAndWait, cancels a child context with a distinct cause
    (errFirstEventTimeout) on timeout, disarms on the first event, and maps the
    cause to a distinct session start timeout: no first turn within … error.
  • internal/execution/engine.go — ExecutionRequest.FirstEventTimeout.
  • internal/models/spec.go / testcase.go — first_event_timeout_seconds
    (eval Config + per-task *int override) and validation (>= 0; 0 disables).
  • internal/orchestration/runner.go — firstEventTimeout(tc) resolver, set on
    every request in buildExecutionRequest (covers initial + follow-up turns).
  • schemas/eval.schema.json, schemas/task.schema.json — new field (required
    because config uses additionalProperties: false).
  • site/.../reference/schema.mdx, site/.../guides/eval-yaml.mdx — docs.
• Important decisions:
  • Opt-in, default 0 (disabled) so existing specs are byte-for-byte
    unchanged; downstream long-turn suites enable it explicitly.
  • Fire on the first event of ANY type — a true session-start hang emits no
    events at all, so any event proves the engine is live; this errs toward never
    false-aborting a slow first turn.
  • context.WithCancelCause + context.Cause is used (race-free) to
    distinguish a first-event abort from the overall timeout_seconds deadline and
    from CancelOnSkillInvocation.
• Follow-ups / known gaps: the underlying stall likely also warrants a
  bootstrap/first-request deadline in github/copilot-sdk (surface a
  session.error instead of silence); waza defends regardless. Choosing a
  sensible non-zero default could be a later change once it's been exercised in CI.

Type of change

• Bug fix
• New feature
• Documentation update
• Refactor or maintenance
• CI/CD or release change

Validation

• go test ./... — full suite green locally (incl. the new tests below).
• make lint or golangci-lint run — golangci-lint (v2) reports zero
  issues on the changed files (gofmt-clean, govet enable-all,
  errcheck, staticcheck).
• Docs site checked, if docs changed — added the field to the schema
  reference and the eval-YAML config table.
• Web/dashboard checks run, if web/ changed — n/a (no web/ change).
• Manual validation completed: new tests assert (a) the watchdog aborts a
  no-event session near its tiny budget rather than the large overall deadline,
  (b) it disarms when the first event arrives (no false abort), (c) the collector
  signal closes on the first event and is idempotent, (d) the runner resolves
  spec/task/disable, and (e) config validation rejects negatives / allows 0.

New tests:

• internal/execution/copilot_first_event_test.go —
  TestSessionEventsCollector_FirstEvent_ClosesOnFirstEvent,
  TestCopilotExecute_FirstEventTimeout_AbortsSessionStartHang,
  TestCopilotExecute_FirstEventTimeout_DisarmsOnFirstEvent.
• internal/orchestration/runner_test.go — TestFirstEventTimeout_Resolution.
• internal/models/{testcase,spec}_test.go — negative-rejected / zero-allowed.

Documentation

• README updated, if user-facing behavior changed — n/a (no README surface).
• site/ docs updated — schema reference + eval-YAML config table.
• Examples updated, if relevant — n/a.
• Not applicable

Risk and rollback

• Risk level: Low. The feature is fully opt-in: with first_event_timeout_seconds
  unset/0, Execute takes exactly the prior path (sendCtx == ctx, no timer,
  no goroutine) and all existing tests pass unchanged.
• Rollback plan: revert the commit; no migrations, no persisted state, no
  schema-breaking change (the new property is additive and optional).

Notes for reviewers

• The core logic is the watchdog block in copilot.go around SendAndWait.
  Please scrutinize the cancellation precedence: CancelOnSkillInvocation
  (checked first) → errFirstEventTimeout (distinct cause) → the overall
  context.DeadlineExceeded. context.Cause(sendCtx) is what disambiguates them.
• The first-event signal lives at the top of SessionEventsCollector.On (guarded
  by a sync.Once), so it can't double-close and disarms on the very first event.
• Local lint shows 3 pre-existing gofmt hits on untouched files
  (copilot_client_wrappers.go, generate.go, git.go) — a Windows CRLF
  working-copy artifact, not present in the LF repo blobs and not in this diff.