2026-11-14 18:30:15 +00:00
# Execution Controls Review
Reviewed implementation stages 1– `57b62d3` , the
[implementation plan ](implementation.md ), the accepted
[feature roadmap ](execution-controls.md ), and the applicable architecture,
testing, documentation, and agent policies.
## 1. Complete The Public Prepared-Notification Contract
2026-11-14 19:45:18 +00:00
Priority: P3. Status: complete. Owning stage: Stage 8.
2026-11-14 18:30:15 +00:00
Location: [RunRequest.OnPrepared GoDoc ](../../types.go#L97 ).
The public GoDoc describes synchronous delivery, detached ownership, held
admission, and split preparation, but omits two explicitly selected lifecycle
facts:
- Notification occurs at most once per logical execution, when execution
reaches that point before the first generation. Transient retries and
structural repair do not repeat it.
- The callback receives the operation context, including the selected operation
deadline when enabled and inherited parent cancellation. In coordination this
is distinct from the parent context delivered to the next-turn callback.
These facts are already implemented by the
[shared execution boundary ](../../internal/usecase/runner.go#L186 ) and covered
by the notification, retry/repair, and coordinator contract tests. They are also
expressly selected in the roadmap's
[accepted callback decision ](execution-controls.md#3-what-is-the-prepared-details-callback-contract ).
However, Go declarations and GoDoc own the exact public API contract; consumers
should not need a temporary roadmap or implementation inspection to discover
invocation cardinality or the scope of their callback's context.
Required remediation: add these two facts to the field's GoDoc. Preserve
conditional delivery and cooperative cancellation; do not promise notification
for every failed request, forced callback interruption, or terminal observation
after panic. This is a documentation completion, not a runtime change. Existing
behavioral tests already cover these semantics; duplicate tests are unnecessary.
2026-11-14 19:45:18 +00:00
Completion: expanded the field's GoDoc to state invocation cardinality,
non-repetition during retry/repair, and operation-context scope, including the
distinction from the coordinator's next-turn callback context. Runtime behavior
is unchanged. GoDoc rendering and the existing focused race-enabled notification,
retry/repair, and coordinated-budget tests passed.
2026-11-14 18:30:15 +00:00
## Stage Review Summary
| Stage | Result |
| --- | --- |
| 1 — API and conversion | Selected fields and sentinel are present; callback conversion captures the chosen function and detaches details only when selected. |
| 2 — Ordinary timeout | One internal scope covers ordinary execution; per-invocation cause attribution and public error projection precede terminal observation. |
| 3 — Split preparation | Handles retain duration and callback without an idle timer; claim/discard and cleanup behavior are preserved. |
| 4 — Prepared notification | Both execution paths use the actual shared snapshot, with context checks and held admission; retries and repair do not notify again. |
| 5 — Phase budgets | Tests cover preparation, capacity waiting, retry backoff, generation/repair, validation, notification time, and stable terminal outcomes. |
| 6 — Ownership and failures | Public tests cover detached messages, cache metadata, nested parameters, schema, credentials, frozen sources, retained diagnostics, and panic cleanup. |
| 7 — Coordination | Fresh turn budgets, parent-context assessment, released capacity, sibling use, observer composition, and explicit grouping are covered. |
2026-11-14 19:45:18 +00:00
| 8 — Documentation and example | Maintained example, consumer/internal documentation, and the completed canonical GoDoc reflect the feature; finding 1 is resolved. |
2026-11-14 18:30:15 +00:00
No runtime correctness defect, additional architectural gap, or inadvertently
strengthened caller restriction or guarantee was identified in this review.
## Validation
- The complete package suite passed under `go test -race ./...` when combining
the initial run with successful reruns of `internal/configuration` and
`internal/llm` . Those two packages initially failed solely because the sandbox
disallowed their local `httptest` listeners; their reruns permitted listeners.
- `go vet ./...` passed using Go 1.27.3 with `GOTOOLCHAIN=local` , `GOWORK=off` ,
and offline module resolution.
- Changed Go files are formatted. `git diff --check` and local document-target
checks passed. No implementation, dependency, policy, or release files were
changed during the review.
