Exec Runtime

Exec Runtime

The shared runtime that executes foreground commands, background processes, services, and PTY sessions.

See also Processes and PTY.

The exec runtime is unified across shell, process_start, and the related process tools. It applies standardized environment defaults before request-specific environment overrides.

shell

Model-facing prompt: run a command.

Schema highlights:

• command: string required
• description: string required
• optional workdir
• optional timeout
• optional output filters
• optional tty: boolean = false
• optional run_in_background: boolean = false

Notes:

• description must be non-empty.
• numeric timeout must be a positive integer.
• run_in_background skips the foreground timeout path and returns a process id.
• Do not append & when using run_in_background.

Examples:

{"command":"npm test","description":"Run frontend tests"}
{"command":"python3 -i","description":"Start Python REPL","tty":true,"run_in_background":true}

Runtime ownership

The unified runtime owns:

• foreground commands
• background processes
• services
• PTY sessions

For terminal behavior:

• tty: false uses stdout/stderr pipes.
• tty: true uses the PTY path and combines stdout/stderr into combined.
• PTY output is transcripted through the same bounded runtime buffers as pipe output.
• PTY can change command behavior and should not be enabled for plain builds/tests unless needed.

Standardized exec env

All foreground, background, service, and PTY spawns apply EXEC_ENV_DEFAULTS before request env overrides. Request-provided env values win.

Key	Value	Why
NO_COLOR	1	Keep transcripts stable and readable without ANSI color noise.
TERM	dumb	Discourage interactive/full-screen terminal behavior unless tty=true.
LANG	C.UTF-8	Provide deterministic UTF-8 locale.
LC_CTYPE	C.UTF-8	Preserve UTF-8 character classification.
LC_ALL	C.UTF-8	Avoid locale-specific output drift.
COLORTERM	empty	Disable color auto-detection.
PAGER	cat	Prevent commands from blocking in pagers.
GIT_PAGER	cat	Prevent git from blocking in pagers.
GH_PAGER	cat	Prevent GitHub CLI from blocking in pagers.
REFACT_EXEC	1	Marker that a process is running under Refact exec.

Related process tools

The process-facing tools and their cursor/notification model are documented in Processes and PTY.