---
name: subprocess_stream
kind: function
lang: go
domain: core
version: "1.0.0"
purity: impure
signature: "func SubprocessStream(ctx context.Context, name string, args []string, env []string, stdin io.Reader) (<-chan StreamEvent, <-chan StreamResult)"
description: "Lanza un subproceso y retorna dos canales: uno con StreamEvent (linea de stdout/stderr con timestamp) y otro con un unico StreamResult (ExitCode, Err, DurationMs). Cancelar ctx envia SIGTERM al proceso; si no termina en 2s, SIGKILL."
tags: [subprocess, exec, stream, stdout, stderr, process, concurrency, io, primitiva]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: [bufio, context, fmt, io, os, os/exec, sync, syscall, time]
params:
  - name: ctx
    desc: "Contexto de cancelacion. Al cancelar, el proceso recibe SIGTERM; si no muere en 2s, SIGKILL. Usar context.WithTimeout para acotar duracion maxima."
  - name: name
    desc: "Nombre o path del ejecutable a lanzar (ej. 'echo', '/usr/bin/python3')."
  - name: args
    desc: "Argumentos del proceso. Puede ser nil o vacio."
  - name: env
    desc: "Variables de entorno adicionales en formato 'KEY=VALUE'. Se concatenan con os.Environ(). Puede ser nil."
  - name: stdin
    desc: "Stdin del proceso. Puede ser nil si el proceso no necesita entrada."
output: "Dos canales: events (<-chan StreamEvent) cerrado cuando ambos pipes EOF; result (<-chan StreamResult) con exactamente un valor cuando el proceso termina. El caller DEBE consumir events hasta cierre o cancelar ctx para evitar bloquear goroutines internas."
tested: true
tests:
  - "echo stdout llega como evento y ExitCode 0"
  - "stderr llega como evento con stream stderr"
  - "exit code no-cero se reporta en StreamResult"
  - "ctx cancelado termina el proceso"
  - "multiples lineas stdout"
test_file_path: "functions/core/subprocess_stream_test.go"
file_path: "functions/core/subprocess_stream.go"
---

## Ejemplo

```go
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

events, results := core.SubprocessStream(ctx, "grep", []string{"-rn", "TODO", "."}, nil, nil)

for ev := range events {
    switch ev.Stream {
    case "stdout":
        fmt.Println(ev.Line)
    case "stderr":
        fmt.Fprintln(os.Stderr, "[stderr]", ev.Line)
    }
}

res := <-results
if res.ExitCode != 0 || res.Err != nil {
    log.Printf("grep exit=%d err=%v duration=%dms", res.ExitCode, res.Err, res.DurationMs)
}
```

## Notas

- El canal `events` tiene buffer de 64. Si el caller deja de consumir y el buffer se llena, las goroutinas internas se bloquean hasta que haya espacio o el ctx sea cancelado.
- El scanner de cada pipe tiene un buffer de 1 MB para tolerar lineas muy largas (progreso de CLIs tipo sd-cli, barras ANSI largas).
- Los structs `StreamEvent` y `StreamResult` se declaran en el mismo archivo para que el paquete `core` los exporte sin imports adicionales.
- Generaliza el patron de `claude_stream_go_core` desacoplando el lanzamiento de subprocesos del protocolo especifico de claude (NDJSON/stream-json). `claude_stream_go_core` puede reimplementarse internamente usando esta funcion como primitiva.
- `cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true}` crea un process group propio; SIGTERM/SIGKILL se envian con `Kill(-pgid, sig)` para matar tambien los procesos hijo del hijo.