feat: improve codex trace filtering

scripts/src/help.ts

@@ -390,9 +390,12 @@ function codexHelp(): unknown {
     usage: [
       "bun scripts/cli.ts codex trace list [--root ~/.codex] [--limit 30]",
       "bun scripts/cli.ts codex trace active [--root ~/.codex]",
+      "bun scripts/cli.ts codex trace grep --session <id> --pattern 'playwright|auth-login-failed' [--since ISO]",
+      "bun scripts/cli.ts codex trace grep --session <id> --messages --pattern 'Playwright|web-probe'",
+      "bun scripts/cli.ts codex trace grep --session <id> --failed-only [--tool exec_command]",
       "bun scripts/cli.ts codex trace grep --pattern 'playwright|auth-login-failed' [--file sessions/...jsonl] [--since ISO]",
       "bun scripts/cli.ts codex trace collect [--root ~/.codex] [--output .state/codex-trace/<timestamp>] [--limit 30]",
-      "bun scripts/cli.ts codex trace show --file sessions/2026/06/16/<session>.jsonl [--root ~/.codex] [--tail-bytes 12000]",
+      "bun scripts/cli.ts codex trace show --session <id> [--root ~/.codex] [--tail-bytes 12000]",
       "bun scripts/cli.ts codex deploy <commitId> # disabled legacy deployment entry",
       "bun scripts/cli.ts agentrun get tasks --queue commander --limit 20",
       "bun scripts/cli.ts agentrun describe aipodspec/Artificer",
@@ -444,8 +447,8 @@ function codexHelp(): unknown {
       defaultRoot: "~/.codex",
       defaultIncludes: ["sessions/*.jsonl", "history.jsonl", "shell_snapshots", "*.log", "trace-named text files"],
       defaultExcludes: ["auth/config", "sqlite", "cache/.tmp/generated_images/plugins/skills"],
-      active: "codex trace active finds open Codex session JSONL files from /proc without requiring lsof.",
-      grep: "codex trace grep parses JSONL records and returns bounded summaries/signals instead of printing whole matching lines.",
+      active: "codex trace active finds open Codex session JSONL files from /proc without requiring lsof and prints copyable session ids.",
+      grep: "codex trace grep supports --session <id>, --messages, --tools, --tool <name>, and --failed-only. It defaults to active/recent sessions, uses rg/raw prefiltering for speed, prioritizes messages/tool inputs, and folds tool outputs unless --include-output or -o wide is explicit.",
       output: "Default output is concise text/table; use -o json|yaml|name|wide for machine or wider output.",
       collectOutput: ".state/codex-trace/<timestamp>/manifest.json",
       note: "Use --root <dir> to scan another local Codex trace directory; collect copies bounded files locally and never uploads or deletes source files.",