rtk discover overcounts shell-wrapper parser fallbacks as top unhandled commands

Summary

rtk discover / unhandled-command reporting appears to overcount shell-wrapper activity as real missing commands when command telemetry falls back to parsed_cmd.type="unknown".

In practice, this surfaces high-volume pseudo-commands like:

• $B goto
• $B screenshot
• $B responsive
• $B snapshot
• $B console
• eval "$(...)"
• [ / if [
• python3 << 'PYEOF'
• rev-parse

These are not all independent end-user commands that RTK should necessarily support directly. Many are:

1. wrapper-script internals,
2. multi-line shell programs,
3. shell builtins / syntax fragments, or
4. commands already rewritten or orchestrated by higher-level tooling.

The result is a noisy OP UNHANDLED COMMANDS report that looks like actionable product gaps, but is often just parser fallback noise.

Concrete example

On April 22, 2026, one local session produced this top-unhandled summary:

Command	Count
$B goto	62
# Check	36
eval "$(..	36
$B screenshot	25
[	21
# Test	19
python3 <<	16
$B responsive	13
$B snapshot	12
'^RXRESUME_API_KEY='	12
gstack-update-check	11
if [	9
null	9
eval	8
$B console	7
rev-parse	7

This strongly suggests the aggregation layer is counting parser fallbacks / shell fragments instead of meaningful top-level commands.

Evidence

I inspected local Codex session JSONL output and found cases where complex shell invocations are stored as parsed_cmd: [{"type":"unknown", ...}] even when the underlying command is clearly a wrapper script or structured shell program.

Representative examples from local session logs:

• multi-line shell wrapper using git rev-parse, gstack-slug, find, tail, etc. recorded as one parsed_cmd.type="unknown"
• omx explore --prompt ... recorded as parsed_cmd.type="unknown"

That means a downstream summarizer can easily misclassify wrapper-generated activity as “top unhandled commands”.

Expected

Unhandled-command reporting should focus on meaningful top-level commands that represent actual RTK support gaps.

It should avoid or down-rank:

• shell builtins / syntax fragments ([, if [, heredoc markers)
• wrapper-private env-var assignments / grep patterns
• comment lines / sentinels (# Check, # Test)
• higher-level orchestrator internals that should be attributed to their parent tool rather than counted as standalone missing commands
• giant multi-line shell programs that parser fallback marks as unknown

Actual

These parser fallbacks are surfaced as if they were genuine missing commands, which creates a misleading “top unhandled commands” list.

Likely root cause

There seems to be a mismatch between:

1. raw exec telemetry / parser fallback (parsed_cmd.type="unknown"), and
2. the analytics layer that builds the unhandled-command summary.

If the analytics layer treats every unknown parse as a candidate missing command without filtering shell syntax / wrappers / orchestrator internals, false positives are inevitable.

Relation to existing issues

This feels adjacent to, but distinct from:

• #1406 (Top unhandled commands from rtk discover)
• #1441 (rtk discover reports false-positive missed savings for hook-rewritten commands)

Those issues focus on command coverage and pre-hook vs post-hook classification.

This issue is narrower: even before support classification, the parser/aggregation layer appears to emit low-quality “commands” that should never make it into the user-facing top-unhandled list.

Potential fixes

A few possible approaches:

1. Filter obvious shell syntax / fragments before adding entries to unhandled summaries.
2. Collapse wrapper internals under a parent command when the invocation is clearly generated by a wrapper/orchestrator.
3. Treat parsed_cmd.type="unknown" as low-confidence unless it resolves to a simple single command token.
4. Add heuristics for heredocs, comments, env assignments, and multi-line scripts so they do not become first-class “commands”.
5. Show confidence or source kind in discover output (explicit command vs parser fallback vs wrapper-derived).

Why this matters

Without filtering, rtk discover can send users toward the wrong action:

• opening feature requests for shell syntax,
• assuming RTK misses commands it should not claim to support directly,
• or overlooking real product gaps hidden beneath wrapper-noise.

Environment

• Observed on: April 22, 2026
• Client context: Codex / OMX / gstack-heavy shell-wrapper workflows
• OS: macOS
• Repo involved in wrapper activity: mixed local automation + browse wrappers