[jameswnl]

Summary

First piece of running sandbox steps through OpenShell exec instead of an exposed HTTP server. This adds two modules that are not wired into anything yet:

• spawner/exec_request.py builds the JSON request the sandbox step CLI (python -m lightspeed_agentic.step) reads on stdin.
• spawner/step_protocol.py reads the CLI's stdout/stderr and maps its exit code and result to the runner's existing step outcomes.

The CLI contract is the sandbox's .ai/spec/what/step-cli.md. The CLI runs as the same user as the agent's tools, so its output is treated as untrusted.

Request builder

• Fields match the CLI's StepRequest: query, context, systemPrompt, outputSchema, timeout_ms, stepId, runDir, traceparent. Unknown keys are rejected by the CLI, so allowedTools/deniedTools are never sent (a warning is logged if present) and tracestate is dropped.
• stepId is derived from the step name: a slug plus a hash of workflow id, step name and attempt, always matching ^[a-z0-9-]{1,40}$.
• Requests are capped at 1 MiB minus 64 KiB. check_exec_message_size(stdin, env, argv) checks the whole exec message against the gateway's 1 MiB limit, for the transport to call.
• A step whose MCP config has plain headers values is refused, because exec mode has no safe way to pass them yet. The error names the server, never the values.

Outcome rules

• A step is completed only from a valid result line on stdout.
• Exit 0 without a valid result line is a protocol violation; result.json is not used as a fallback, because a process started by the agent can replace it.
• Exit 4 or a lost stream: result.json is read only for a fixed-vocabulary diagnostic (status code, success flag, presence flags for a fixed list of fields, byte size). No text from the file is carried. The step fails, is not retried, and the sandbox is marked unsafe to reuse.
• Exit 2, 1 and 3 fail without retry. A 502 result stays transient, as on the HTTP path; other errors (deadline, kill, unexpected exit) are not retried.
• Reading is bounded: 256 KiB per event line, 4 MiB for the result line, 64 MiB of stdout, JSON nesting depth 64, a 64 KiB allowance for output before the first protocol line. The stderr tail is redacted before it is shortened.

Testing

• Tests written first, including adversarial input (huge lines, NaN, extra keys, two result lines, partial lines, invalid UTF-8, forged result files, secrets crossing truncation boundaries).
• Golden fixtures under tests/unit/spawner/fixtures/step_cli/ were captured from the real step CLI (sandbox commit bca5ad01) using its own fake providers, with requests built by this builder. generate.py and the README describe how; expected outcomes are written by hand from the spec.
• Unit suite: 2547 passed, 5 skipped. black and ruff clean.

Not in this PR

The exec transport, the spawner changes and the runner wiring come in later PRs. Nothing here changes runtime behaviour.

🤖 Generated with Claude Code

[beesarmy]

Reviewed head e456d06 against base 37a0840. No blocking findings remain in scope.

Approval covers only the new, currently unused protocol/parser and request-builder modules and their tests/fixtures. Inspected strict bounded parsing, request serialization and size limits, plain MCP-header rejection, stdout-only completion, diagnostic-only file outcomes, metadata-only diagnostics, and preservation of lease-taint and retry decisions. These modules do not wire in or enable exec transport.

Read-only source/test review: local unit and fixture-generation results are implementer evidence, not independently rerun here. Confirmed exact-head build, lint, unit-tests and e2e checks succeeded. Integration did not run because the workflow path filter excludes this diff; that is not an integration pass.

No live gateway, sandbox image, end-to-end transport, finite-tool enforcement, secret-bearing MCP activation, or warm-lease safety is established by this approval. Wiring and activation require separate review and evidence.