refactor(custom-engine): extract customTransport interface with localTransport (#51)

[zpzjzj]

Summary

Resolves #51. Introduces an internal customTransport interface seam in the agent package so the planned HTTP transport (Phase 2) can drop in without rewriting the local-transport logic or the shared result handling. Pure refactor — no behavior, config, contract, or CLI change.

What changed

CustomAgent.Run now does three transport-agnostic steps and dispatches the rest:

1. selectTransport — maps engine.custom.transport to an implementation (localTransport, or the http not-yet-implemented stub). HTTP later just returns &httpTransport{} from this one switch.
2. prepareRun — builds the effective timeout, the full template variable set, and the marshaled SessionInput into a customRunPrep.
3. assembleResult — maps a transportOutcome to a SessionResult, applying the shared exit-code / error semantics.

The local-specific work — resolving I/O files, persisting the input, clearing a stale output, building+executing the command, and reading the result payload from output_file or stdout — moves behind localTransport.run in the new internal/agent/custom_local.go, which returns a uniform transportOutcome.

runLocal / finishLocal / localRunContext are removed; registerFrameworkIO (bool flag-param) becomes appendFrameworkFiles([]string).

Behavior-preserving (verified)

• Two-tier errors: setup errors (pre-exec) still return errorResult(0); exec-phase failures are carried in transportOutcome.execErr so a partial result is still assembled — including the post-timeout fresh-context output read.
• raw vs stdout kept distinct so a bookkeeping output_file is never graded as a text-format answer.
• Framework-file registration keeps the "input always, output iff produced-or-cleared" rule.
• The http transport still returns the exact custom engine http transport is not yet implemented error.

Test plan

• make test (go test -race ./...) — all green; internal/agent/custom_test.go (~50 TestCustomAgent_RunLocal_*) unchanged and passing (the safety net).
• make verify (fmt + vet + revive + golangci-lint) — 0 issues.
• make e2e custom-engine suite — TestPipeline_CustomEngine_{LocalTransport,Validate,RejectsMissingEnvVar} all pass.

Notes for reviewers

• No user-facing doc/config change is expected; the design doc's transport sections and the writing-evals guides are untouched. A reviewer seeing a functional diff in those would indicate the refactor leaked scope.
• Follow-ups Custom Engine: extract template-resolution into a leaf customengine package #50 (leaf customengine package + unify token parsers) and Custom Engine: extract agent-specific metadata out of generic ExecOptions #49 (move case metadata out of generic ExecOptions) remain open and are independent of this seam.

🤖 Generated with Claude Code

[zpzjzj]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. What shall we delve into next?

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[lbfsc]

LGTM