Module driver 

@arch:layer(kg_store) @arch:role(substrate) @arch:see(.yah/docs/working/yah-task-runs.md)

PTY subprocess driver — spawn commands, capture output as append-only chunks, handle SIGTERM/SIGKILL with a grace period, and mark stale Running runs as Lost when the daemon restarts.

Tier 2 side-channel (yah-log shims)

When SpawnOpts::log_fd_enabled is true (the default), the driver creates a named pipe (FIFO) and exports two env vars into the child:

• YAH_TASK_RUN — the TaskRunId as a hyphenated UUID string.
• YAH_LOG_PIPE — absolute path to the FIFO.

The child opens YAH_LOG_PIPE for writing and emits JSON-lines. The driver reads those lines in a background thread and stores them as [EventSource::Shim] events.

Why FIFO instead of a raw fd? portable-pty calls close_random_fds() in its pre_exec hook, closing every fd ≥ 3 before exec. A raw-pipe write fd is always ≥ 3 and would be closed before the child could use it. Opening a FIFO by path requires no fd inheritance.

Wire format — one JSON object per line:

{"level":"info","target":"myapp::module","msg":"text","fields":{"key":"val"}}

Optional shim-identity keys: "_lib" (string), "_lib_ver" (string). Unknown keys in fields pass through as freeform JSON.

The driver holds the write end of the FIFO open until the run lifecycle task completes, which triggers EOF for the receiver thread. The FIFO file is deleted after the receiver thread drains the last line.

On non-Unix platforms YAH_TASK_RUN and YAH_LOG_PIPE are not exported. Shim libraries must treat absent YAH_TASK_RUN as “not inside a TaskRun”.

Structs

SpawnOpts

Options for TaskDriver::spawn_run.

TaskDriver

Manages in-flight task runs for a single camp.

Enums

DriverError