bug(agents): large inline child instructions can terminate Pi before RPC startup

[aintoniodev]

Before submitting

• I searched open and closed issues and did not find a report of this problem.
• I reviewed this report and removed credentials, tokens, private paths, hostnames, and other sensitive data.

Problem

On macOS, the installed gentle-pi 3.4.0 subagent runner repeatedly fails to start gentle-ai-explore and gentle-ai-worker. The parent reports pi exited with code unknown before agent_settled. Stored tasks show zero turns, tools, and tokens and no child session path. Ordinary Pi RPC startup succeeds; the failure is specific to the subagent launch shape.

The runner's childArguments() passes the complete agent instructions as one literal --append-system-prompt CLI argument (lib/agents-runner.ts). In a controlled subprocess reproduction, passing the explorer's ~4.3 KB instructions inline caused the child to exit with code: null, signal: SIGKILL, no stdout/stderr, and no get_state response. Passing the same text through a temporary prompt file path to --append-system-prompt returned get_state and exited 0. A 1000-character inline prefix succeeded; larger ~1250-2000-character inline arguments triggered the early signal in this environment. The source of SIGKILL is not established, so the report does not attribute it to Pi, macOS, or a particular security policy.

The runner listens for the child exit event using only code and formats null as unknown, discarding Node's separate signal argument. This hides a decisive diagnostic.

Steps to reproduce

1. On macOS with Pi 0.87.1 and gentle-pi 3.4.0, request a minimal subagent_run using the installed gentle-ai-explore agent; no tools or file edits are needed in the delegated prompt.
2. Observe pi exited with code unknown before agent_settled and inspect the task record: no child session path, zero turns and tools.
3. As a control, spawn Pi in RPC mode with --append-system-prompt set to a synthetic string of about 2000 characters and send {"id":"probe","type":"get_state"}. Capture Node's exit(code, signal) pair and stdout/stderr.
4. Repeat with the identical string written to an owner-only temporary file and pass its path as --append-system-prompt. Remove the temporary file and session directory after each run.
5. In the observed setup, the inline case exited within ~10-20 ms with SIGKILL and no RPC output; the file-path case returned get_state and exited 0. Short inline arguments also worked.

Expected and actual behavior

Expected: long agent instructions should reach the child reliably, or launch failures should identify the terminating signal; no unrelated child task should be lost before the first run event.

Actual: package-owned explorer and worker launches fail before agent_settled with an unknown exit code. The direct controlled comparison isolates long inline CLI arguments as the reproducible trigger here, while the current error discards the signal.

Potential fix for investigation: use a bounded/path-based transport for agent instructions rather than putting arbitrarily long instructions in argv; preserve signal in runner exit diagnostics. Add a regression covering a large agent definition and cleanup of temporary transport artifacts.

gentle-pi version

3.4.0

Pi version

0.87.1

Operating system

macOS

Relevant logs or error output (optional)

Subagent gentle-ai-explore failed: pi exited with code unknown before agent_settled
Controlled child exit (inline instructions): {"code":null,"signal":"SIGKILL"}; no stdout/stderr
Controlled child exit (same instructions via temporary file): {"code":0,"signal":null}; get_state response present

[Alan-TheGentleman]

I tried to reproduce this on macOS arm64 with Pi 0.87.1 and the local gentle-pi 3.7.0 checkout. The installed definitions select openai-codex/gpt-6-luna:high for gentle-ai-explore and openai-codex/gpt-6-sol:medium for gentle-ai-worker.

In controlled RPC startup probes, both agents’ instruction texts reached get_state when passed inline and via a private temporary file. Synthetic 1,000, 1,250, and 2,000-character inputs also worked (14/14 trials). With the parsed installed instructions passed inline, both agents reached get_state with the ambient model and with each model explicitly selected (6/6 trials). No probe exited or timed out before the response.

This does not invalidate the reported SIGKILL on gentle-pi 3.4.0. These probes did not send a model prompt or load extensions, so they do not reproduce the complete subagent launch. I cannot reproduce the pre-RPC failure in this environment or isolate its cause; I would keep the issue open while #1382 is under review.

[cocoe25]

Additional host evidence strongly corroborates the transport diagnosis and the direction in #1382.

Environment

• macOS 27.0 (26A428), arm64
• Node 24.7.0
• Pi 0.87.1
• gentle-pi 3.7.0, also the current npm release

Observed failure

• The exact gentle-ai-explore instruction body is 1,171 bytes.
• Starting Pi RPC with that literal value in --append-system-prompt exits with process return code -9 (SIGKILL) before get_state or any other RPC event. There is no stdout or stderr.
• A 970-byte literal succeeds on the same host; 1,100-byte and 1,171-byte literals fail.
• The failure also reproduces with --system-prompt and with extensions, skills, and prompt templates disabled, which removes the active extension set and model invocation as causes.
• Pi releases 0.84.0, 0.85.0, 0.86.0, and 0.87.0 all showed the same inline failure in isolated temporary installs. The same 1,171-byte content passed by file path reached get_state on 0.86.0 and 0.87.0.

End-to-end control

Using the installed 3.7.0 AgentRunner and real gentle-ai-explore definition, only the spawn transport was replaced: instructions at or above the threshold were written to an owner-only 0600 temporary file and that path was passed to --append-system-prompt. The actual explorer then completed a read-only probe successfully: status=completed, 2 turns, 1 tool call, correct result, and no task error.

The current installed runner has reverted to the published inline behavior after reinstall/update:

if (request.agent.instructions.length > 0) args.push("--append-system-prompt", request.agent.instructions);

A traced failing child reported code=null, signal=SIGKILL; the current exit handler surfaces this as an unknown code because it drops the signal. A matching macOS AppleSystemPolicy log said it was unable to apply the provenance sandbox to the Node executable. That log is a useful lead, but it does not prove which component issued the kill.

This evidence supports both parts of #1382: file-backed transport for large child instructions and preserving the child exit signal. A valuable regression would run the real runner with a greater-than-1,000-byte explorer prompt and require RPC readiness plus task settlement, not only assert the spawned argv.