In `@src/plugins/agents/builtin/kiro.ts`:
- Around line 117-123: When handling the child process close in the
proc.on('close', ...) callback, don't treat exit code 0 as a success unless the
version regex actually matched; update the logic in that handler (the proc.on
close block that currently inspects stdout/stderr and calls resolve) to check
versionMatch before resolving success: true — if versionMatch is falsy, resolve
with success: false and include a clear error message (e.g., "Unexpected version
format") plus the raw stdout/stderr for diagnostics; keep the existing behavior
for non‑zero codes but ensure the same diagnostic info is included in the error
payload.
- Around line 92-100: The runVersion function currently spawns the resolved
executable path with shell: true; change this to shell: false to avoid
unnecessary shell invocation when 'command' is a resolved path, and only enable
shell: true when necessary for platform-specific behavior (e.g., wrap with a
runtime check for Windows if you need cmd.exe semantics). Update the spawn call
in runVersion (the const proc = spawn(command, ['-V'], { ... })) to set shell:
false and adjust any Windows handling around command resolution or quoting so
the direct spawn works cross-platform.

In `@src/plugins/agents/builtin/codex.ts`:
- Around line 182-214: Codex currently sets structuredOutputFormat: 'jsonl' and
enables --json in buildArgs but doesn't parse JSONL events; update the Codex
plugin by overriding execute() (similar to the Claude/OpenCode implementations)
to parse JSONL lines from STDOUT into structured events and forward parsed
events to onStdout/onEvent handlers when options?.subagentTracing is true, or if
you intend not to support JSONL remove the structuredOutputFormat declaration
and the --json flag logic in buildArgs; look for the Codex class, its buildArgs
method, and the base execute/onStdout behavior to implement the JSONL parsing
and event emission consistently with other agents.

In `@src/plugins/agents/builtin/gemini.ts`:
- Around line 168-195: The Gemini agent currently declares
structuredOutputFormat as 'jsonl' and pushes '--output-format', 'stream-json' in
buildArgs but does not parse JSONL; either implement JSONL parsing by adding
parseJsonlLine() and updating execute() in the Gemini agent to read stdout
line-by-line, parse each JSONL record (handling errors and end-of-stream) and
emit/subagent-trace accordingly (also mimic Claude/OpenCode by adding
'--verbose' when using 'stream-json' if required), or remove
structuredOutputFormat and stop pushing '--output-format', 'stream-json' in
buildArgs (and remove any related subagentTracing branching) so the agent
returns raw stdout consistently; refer to the buildArgs, execute,
structuredOutputFormat, and the new parseJsonlLine symbol when making the
changes.

In `@src/logs/persistence.ts`:
- Around line 704-711: The filename filter's newPattern is too strict (only
lower-case hex) and will skip valid logs created by generateLogFilename();
update newPattern to accept any sessionId token (e.g., one or more
non-underscore chars) such as
/^[^_]+_\d{4}-\d{2}-\d{2}_\d{2}-\d{2}-\d{2}_.*\.log$/ and use this relaxed
pattern wherever hasIterationLogs() or similar logic checks the "new" format so
both files.filter(... legacyPattern || newPattern) and hasIterationLogs()
recognise the same new-format filenames. Ensure the updated pattern still
enforces the timestamp and taskId parts and keep legacyPattern unchanged.

In `@src/plugins/agents/builtin/codex.ts`:
- Around line 331-384: The onStdout wrapper in override execute drops JSONL
records split across chunks; fix by buffering incomplete data between calls: add
a persistent buffer (e.g., this._jsonlBuffer or a closure variable inside
execute) and on each incoming chunk prepend the buffer, split on '\n', keep the
last partial line in the buffer, and only parse/forward the complete lines to
onJsonlMessage and to parseCodexOutputToEvents; ensure when the stream ends you
flush any remaining buffered line. Update references: execute,
onStdout/onJsonlMessage, parseCodexOutputToEvents, processAgentEventsToSegments,
and processAgentEvents to use only the complete-line data, preserving the
leftover for the next chunk.

In `@src/plugins/agents/builtin/gemini.ts`:
- Around line 301-354: The onStdout wrapper in execute currently splits each
incoming chunk by '\n' and can drop partial JSONL records that span chunks;
change the wrapper to maintain a persistent buffer string (e.g., let jsonlBuffer
= '') closed over the onStdout callback, append each incoming chunk to it,
extract complete lines by finding newline boundaries, parse/forward only those
complete lines to options.onJsonlMessage (and skip or log malformed JSON), and
keep any trailing partial line in jsonlBuffer for the next chunk; after
extracting complete lines, pass the reconstructed data for display parsing via
parseGeminiOutputToEvents -> processAgentEventsToSegments/processAgentEvents as
before so that parseGeminiOutputToEvents, processAgentEventsToSegments, and
processAgentEvents operate only on full event text.

In `@website/content/docs/plugins/agents/codex.mdx`:
- Around line 133-173: Docs incorrectly state that `--json` is only passed when
tracing is enabled; update the text around the `codex exec` example and the
"Enabling Tracing" section to say that Codex is always invoked with `--json` (so
output is parseable) and that `subagentTracingDetail` (and the TUI keys t /
Shift+T) only control whether Ralph TUI parses/displays the subagent JSONL, not
whether `--json` is used; reference the `codex exec [options]` example and the
`--json` flag and replace any wording like "When tracing enabled" with a clear
statement that `--json` is always included and tracing only affects
display/verbosity.

In `@website/content/docs/plugins/agents/gemini.mdx`:
- Around line 130-169: The docs incorrectly state that `--output-format
stream-json` is optional, but the implementation always appends it; update the
argument construction in the Ralph TUI Gemini launch logic to add
`--output-format stream-json` only when tracing is enabled (e.g., when
`subagentTracingDetail` is not "off"/false or when the TUI trace toggle is
active), and update the documentation to reflect that the flag is only present
when tracing is enabled; locate the code that builds the gemini args (the block
that constructs `gemini [options]` / the array used to spawn the process) and
make the `--output-format stream-json` entry conditional based on the
`subagentTracingDetail`/trace toggle state.

In `@src/plugins/agents/builtin/codex.ts`:
- Around line 201-247: The runVersion function starts a timer that can fire
after proc emits 'close' or 'error', causing a late proc.kill() and duplicate
resolve; fix it by storing the timeout ID (e.g., const timer = setTimeout(...)),
clearTimeout(timer) in both proc.on('error', ...) and proc.on('close', ...)
handlers, and add a simple resolved guard (let settled = false; set settled =
true before each resolve and skip if already true) so proc.kill() and resolve
are not called twice; reference runVersion, proc, timer/timeout and the
'error'/'close' handlers when applying the change.
- Around line 338-405: BaseAgentPlugin currently never calls the
AgentExecuteOptions.onEnd lifecycle hook, so Codex's jsonlBuffer can never be
flushed when the agent exits; implement onEnd invocation in
BaseAgentPlugin.completeExecution() (call options.onEnd?.() after the execution
promise resolves/rejects) and then in src/plugins/agents/builtin/codex.ts (the
override execute method using jsonlBuffer) wrap or rely on that onEnd so the
remaining jsonlBuffer content is parsed and forwarded (flush buffer -> parse
last line(s) to JSON via JSON.parse and emit via
options.onJsonlMessage/options.onStdoutSegments/options.onStdout). Ensure you
reference BaseAgentPlugin.completeExecution, AgentExecuteOptions.onEnd, and the
execute override/jsonlBuffer in codex.ts when making the changes.

In `@src/plugins/agents/builtin/gemini.ts`:
- Around line 308-375: The onStdout wrapper in override execute buffers partial
JSONL lines in jsonlBuffer but never processes leftover content if the process
exits without a trailing newline; update override execute so after calling
super.execute(...) you capture the returned AgentExecutionHandle and attach a
finalization/close/exit callback on that handle (the AgentExecutionHandle
returned by super.execute) to flush any remaining jsonlBuffer: trim and, if
non-empty and startsWith('{'), JSON.parse and call options.onJsonlMessage, then
feed the leftover into parseGeminiOutputToEvents and forward to
options.onStdoutSegments/options.onStdout as the existing logic does, and
finally clear jsonlBuffer. Ensure this uses the same parsing/forwarding code
paths as inside the onStdout wrapper so the last JSONL/event isn't dropped.
- Around line 184-231: In runVersion, prevent the timeout from firing after the
process ends by creating a timeout handle (e.g., const timeout =
setTimeout(...)) and clear it in both proc.on('error') and proc.on('close')
handlers; also guard against double-resolve by tracking a settled flag (e.g.,
let settled = false) and only call resolve (and clearTimeout) when !settled,
then set settled = true before returning. This change should be applied around
the proc, timeout, and the resolve calls inside runVersion to ensure proc.kill()
and resolve are not called twice.

In `@src/tui/output-parser.ts`:
- Around line 94-122: The GeminiEvent interface currently lists undocumented
event kinds "tool_call" and "function_result"; remove those two from the type
union in the GeminiEvent declaration so the union matches the documented event
types ('init' | 'message' | 'tool_use' | 'tool_result' | 'result' | 'error'),
and then search for any code referencing GeminiEvent types "tool_call" or
"function_result" and either remove/replace those usages or add a clear
comment/feature-flag if you intend to keep them for backward/forward
compatibility; ensure TypeScript types and any related tests are updated
accordingly.
- Around line 384-395: The parsing block currently treats Codex and Gemini as
interchangeable by calling parseGeminiJsonlLine when useCodexParser or
useGeminiParser is true; separate the flows so Codex uses a dedicated
parser/formatter (e.g., parseCodexJsonlLine and formatCodexEventForDisplay)
while Gemini continues to use parseGeminiJsonlLine and
formatGeminiEventForDisplay. Update the conditional to check useCodexParser and
call the Codex-specific functions (setting hasJsonl, pushing formatted parts to
parsedParts, and continuing) and only invoke parseGeminiJsonlLine when
useGeminiParser is true to avoid mis-parsing incompatible event shapes.

In `@website/content/docs/plugins/agents/kiro.mdx`:
- Around line 97-102: The docs show a mismatch between the timeout default in
the options table (`timeout = 0`) and the full config example (`timeout =
300000`); update the Kiro docs by either changing the table default to reflect
the example or add a short clarifying sentence below the table referencing the
`timeout` option (mention `timeout`, `0`, and `300000`) that explains `0` means
no timeout and examples like `300000` (ms) are recommended for
production/autonomous runs; ensure the clarification appears near the table and
the full config example so readers see both values together.
- Around line 39-52: The "Select an Agent" step shows an unchanged basic run
command and doesn't demonstrate how to pass agent selection via CLI; update the
Step titled "Select an Agent" so the bash snippet demonstrates agent selection
(e.g., include the CLI flag such as `--agent kiro` or the `--agent-options`
syntax) and/or add a short follow-up run example that uses the agent flag;
ensure the existing toml config block `[agentOptions] agent = "code-reviewer"`
remains and place the corrected CLI example (e.g., `ralph-tui run --prd
./prd.json --agent kiro`) in the Step so readers see both config and CLI ways to
select an agent.
- Around line 18-20: Replace the generic placeholder pointing to
https://kiro.dev with concrete Kiro CLI installation steps: update the fenced
bash snippet in the kiro.mdx docs to reference the downloads URL
(https://kiro.dev/downloads/) and include the common install commands such as
the curl install script (curl -fsSL https://cli.kiro.dev/install | bash) and
Homebrew alternative (brew install kiro-cli), and add a short note about
verifying the install with kiro --version; ensure these commands replace the
existing placeholder block so users can copy/paste directly.

In `@src/plugins/agents/base.ts`:
- Around line 515-517: The call to the plugin lifecycle hook
execution.options?.onEnd?.(result) in completeExecution must be wrapped in a
try/catch so that exceptions from onEnd do not prevent resolution; modify the
completeExecution implementation to invoke execution.options.onEnd(result)
inside a try {} catch (err) {} block (log or swallow the error via processLogger
or a provided logger) and always proceed to resolve/return the result even if
onEnd throws.

In `@src/plugins/agents/base.test.ts`:
- Around line 305-308: The doc comment above the test plugin is inaccurate;
update it to reflect the actual commands used by the test implementation (it
runs "cmd /c echo" on Windows and "echo" on POSIX shells), e.g., change the
sentence from "Uses 'echo' or 'true' commands" to explicitly state "Uses 'cmd /c
echo' on Windows and 'echo' on other platforms" so the comment matches the
behavior around the test plugin in this file.

In `@src/plugins/agents/base.ts`:
- Around line 515-527: The onEnd hook (execution.options?.onEnd) is only called
in completeExecution, so if sandbox resolution fails and the code takes the
early .catch path callers never get onEnd; update the sandbox resolution error
handling to invoke execution.options?.onEnd(resultOrErrorContext) inside that
catch before rethrowing or resolving so plugins always get a final call, and
ensure the call is wrapped in the same try/catch/logging pattern used in
completeExecution (use debugLog when process.env.RALPH_DEBUG) to avoid letting
hook errors change control flow.