Updated BaseRunner.run API

[MattBurn]

Closes Issues

Closes #235

Description

• Replaces the competing capture, silent, stdout, and stderr controls in BaseRunner.run with explicit stdout/stderr stream targets.
• Adds subprocess stream fanout support for Path, string paths, open text streams, callbacks, subprocess.PIPE capture, and multiple destinations using opi.execution.text_stream.TextStreamFanout.
• Adds immutable run result objects opi.execution.base.RunResult and opi.execution.run.SubprocessRunResult with captured output, return-code helpers.
• Deprecates stdin_str, capture, and silent in favor of stdin and stdout/stderr stream targets.
• Adds focused unit tests for capture, fanout, live callbacks, stdin, timeout handling, and invalid stream targets.

---

Release Notes

Added

• Added TextStreamFanout stream-target fanout support for subprocess stdout and stderr destinations. (Updated BaseRunner.run API #238)
• Added immutable subprocess run result objects with return-code and signal helpers. (Updated BaseRunner.run API #238)

Changed

• Changed BaseRunner.run to use explicit stdout and stderr stream targets. (Updated BaseRunner.run API #238)
• Changed BaseRunner.run to return a RunResult instead of subprocess.CompletedProcess or None. (Updated BaseRunner.run API #238)

Deprecated

• Deprecated stdin_str, capture, and silent on BaseRunner.run. (Updated BaseRunner.run API #238)

[MattBurn]

Apologies for the number of CI runs, finally figured out how nox works to check locally in the future

[timmyte]

Apologies for the number of CI runs, finally figured out how nox works to check locally in the future

Anything that could be improved in the docs to make this clearer?

[MattBurn]

I am new to nox so I did not grasp what nox was going to run in CI before pushing. I ended up using uv tool run nox which was a nice and simple way to run everything at once locally. Possibly worth adding to the development guide.

[MattBurn]

Are there any blockers for getting this merged?

[timmyte]

@MattBurn

Very sorry for the long waiting time. I was quite busy.

Looks good. Could you please make the little corrections I remarked before merging. Thanks!!

[timmyte]

@haneug
As I made tiny changes, would you quickly going over this as well

@timmyte

• Run testsuite before merge.

[timmyte]

@haneug
Please review again, as made significant changes and additions.

@MattBurn
If you like to also review, by my guest. I would love to hear your opinion.
I'm very sorry again, for the long delay. It's very nicely structured and documented code.
I enjoyed working with it.

[MattBurn]

Changes look good to me, I originally started this to improve the ergonomics of creating the orca_mm binary in PR #224. With so many changes to how the runner works, do you think it would be best to restart this PR?

[timmyte]

Changes look good to me, I originally started this to improve the ergonomics of creating the orca_mm binary in PR #224. With so many changes to how the runner works, do you think it would be best to restart this PR?

Thanks for your feedback.
From our side there's no need to restart the PR — but feel free to if you'd prefer. I can imagine merging the changes into #224 would be a lot of work, so under the circumstances a rebase and force-push is fine too.

[timmyte]

Had to make some changes. Units test pass fine now.
@MattBurn thanks for adding them so rigorously.