Struct SpawnOpts 

pub struct SpawnOpts {

    pub cwd: PathBuf,
    pub env: Vec<(String, String)>,
    pub label: Option<String>,
    pub initiator: Initiator,
    pub pty_cols: u16,
    pub pty_rows: u16,
    pub stdin_enabled: bool,
    pub pin: bool,
    pub beholder_select: BeholderSelect,
    pub verbatim_output: bool,
    pub log_fd_enabled: bool,
    pub origin: Option<String>,
    pub argv: Option<Vec<String>>,
    pub pipe: bool,
    pub pipefail: bool,
}

Options for TaskDriver::spawn_run.

Fields

cwd: PathBuf

env: Vec<(String, String)>

Env vars set on the child process (merged on top of the current env).

label: Option<String>

initiator: Initiator

pty_cols: u16

PTY column count. Defaults to 80.

pty_rows: u16

PTY row count. Defaults to 24.

stdin_enabled: bool

Enable stdin relay via TaskDriver::send_stdin.

pin: bool

Pin the run so the GC sweep does not drop its output during warm rolloff.

beholder_select: BeholderSelect

Beholder attachment policy. Defaults to BeholderSelect::Auto.

verbatim_output: bool

true when this run’s output is read as text by somebody downstream — a human watching a terminal tile, or a client that promised its caller byte-identical passthrough. Causes Rewriter beholders to decline in Auto mode, since a rewrite changes what that reader gets.

R739-B10 renamed this from tty_attached: a PTY was only ever a proxy for “someone is reading this”, and the proxy broke the moment yah build run moved onto pipes (R739-F6).

log_fd_enabled: bool

Create a side-channel FIFO and export YAH_TASK_RUN / YAH_LOG_PIPE so Tier-2 shim libraries (yah-log-rust, @yah/log) can emit structured events. Has no effect on non-Unix platforms. Defaults to true.

origin: Option<String>

Provenance tag stored on the run’s TaskRunMeta.origin (e.g. Some("terminal") for an interactive shell). None is an ordinary job.

argv: Option<Vec<String>>

Exec this argv directly instead of wrapping cmd in sh -c.

The default sh -c <cmd> is right for a job — the caller wrote a command line and expects a shell to parse it. It is wrong for an interactive shell: sh -c "zsh -l" leaves an inert sh as the PTY’s foreground process group leader, so job control misbehaves, signals go to the wrong process, and anything that reads the foreground pid (a live-cwd probe, say) sees sh instead of the shell the operator is typing into. Handing the exact argv here makes the shell itself the child, which is also the only way to pass -l as a real argv element so .zprofile / .profile actually run.

cmd is still what gets recorded on TaskRunMeta.command, so the run reads the way the caller asked for it. Beholder argv rewriting is bypassed when this is set: the caller has already decided the exact process to exec, and a recorded rewrite=… that didn’t happen would be a lie in the run metadata.

pipe: bool

R739-F6 — spawn on pipes instead of a PTY. Defaults to false, which is the PTY behaviour every existing caller already has.

A PTY is right for an interactive terminal tile: the child gets a controlling terminal, job control works, and isatty says yes, which is what a human sitting in front of it expects. It is wrong for emulating a non-interactive shell invocation, where three PTY properties show up as divergence from running the same command directly (all three measured in R739-F4 against cargo check):

1. isatty(1) is true, so tools colorize — plain error: … arrives as \x1b[1m\x1b[91merror\x1b[0m: …, which also defeats | rg "^error".
2. The line discipline’s ONLCR rewrites every \n the child wrote into \r\n.
3. The terminal merges stderr into stdout, so stream separation is gone by the time anything reads the capture.

In pipe mode the child gets pipe(2) for stdout and stderr, chunks are stored under their true Stream, and TERM is left alone rather than forced to xterm-256color. TaskDriver::resize_run and TaskDriver::foreground_pid have no PTY to answer for and report NotFound / None.

pipefail: bool

R901-B2 — run the sh -c line with pipefail, so a pipeline reports the leftmost failing stage instead of its last one. Defaults to false, i.e. POSIX behaviour, which is what every existing caller has.

Without it a pipeline’s status is the last stage’s and nothing else: cargo check 2>&1 | tail -40 exits 0 on a build with 101 errors, because tail succeeded. That is not a wrapper lying — the wrapper is faithful, and the shell is answering the question it was actually asked — but it is indistinguishable from a green build to everything downstream, including the harness task notification an agent reads to decide whether it is done. On 2026-09-13 two sessions read that 0 as a pass and left cargo check -p yah red camp-wide for ~50 minutes.

Only meaningful when SpawnOpts::argv is None; an explicit argv is not a shell line and has no pipeline to take a status from.

Known cost, accepted deliberately

pipefail also surfaces a producer killed by SIGPIPE, so cargo check 2>&1 | head -40 can now report failure once head closes the pipe early on a build that was fine. That is a false RED, and it is the right trade against the false GREEN above: a red is investigated, a green ends the turn. Prefer | tail over | head on a build line.

Trait Implementations

impl Clone for SpawnOpts

fn clone(&self) -> SpawnOpts

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SpawnOpts

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for SpawnOpts

fn default() -> Self

Returns the “default value” for a type.