Add live hook profiling to launch readiness benchmark

Author: aseembits93

docs/agent-conversation-profile.md

@@ -10,9 +10,10 @@ records.
 `experiment/agent-conversation-profile-modern-codex.mjs` is a compatibility
 variant for newer Codex JSONL streams. It keeps the same CLI and output shape,
 but additionally recognizes Codex `agent_message`, `command_execution`,
-`mcp_tool_call`, `file_change`, and turn/thread lifecycle records. Use it for
-recent `codex exec --json` captures when the original profiler reports most of
-the run as `unknown` or double-counts started/completed MCP calls.
+`mcp_tool_call`, `file_change`, live harness `harness.phase` records, and
+turn/thread lifecycle records. Use it for recent `codex exec --json` captures
+when the original profiler reports most of the run as `unknown`, double-counts
+started/completed MCP calls, or needs to consume live Codex hook timings.
 
 ## Usage
 
@@ -41,9 +42,12 @@ export paths so the run is deterministic and auditable.
 The output directory contains:
 
 - `combined.perfetto.json`: one combined Chrome trace JSON file with one track
-  per conversation.
-- `<left-label>.perfetto.json`: split trace for the left conversation.
-- `<right-label>.perfetto.json`: split trace for the right conversation.
+  per profile row, including conversation, activity, tool group, and command
+  group.
+- `<left-label>.perfetto.json`: split trace for the left conversation, with one
+  track per activity or tool command group.
+- `<right-label>.perfetto.json`: split trace for the right conversation, with
+  one track per activity or tool command group.
 - `combined.snakeviz.prof`: combined synthetic Python pstats profile for
   SnakeViz.
 - `<left-label>.snakeviz.prof`: SnakeViz profile for the left conversation.
@@ -103,14 +107,17 @@ Viewer profiles and the `Time By Activity` summary use derived activity buckets
 that are meant for high-level agent timing:
 
 - `tool`: time spent running an agent action until it completes. This is
-  derived from tool-call and file-change records and, when a matching result
-  exists, spans from the start timestamp to the result timestamp. Tool-result
-  and file-change-result records remain in the raw kind summary but are not
-  counted as separate activity because their time is represented by the parent
-  tool span.
-- `reasoning`: reasoning or thinking records.
-- `user_query`: user-message records.
-- `agent_response`: assistant text response records.
+  derived from live hook phases when present, otherwise from tool-call and
+  file-change records.
+- `reasoning`: reasoning or thinking records. In hook-instrumented traces, this
+  is the measured model span from prompt/result handoff until the next tool
+  call. In raw Codex traces without hook phases, this is inferred from
+  turn-start-to-first-item gaps and tool-result or file-change-result gaps until
+  the next Codex item.
+- `user_query`: user-message records. In hook-instrumented traces, this comes
+  from `UserPromptSubmit` and the session-start boundary.
+- `agent_response`: assistant text response records. In hook-instrumented
+  traces, this comes from the final model span ending at `Stop`.
 - `system`: system-message records.
 - `other`: non-metadata records that do not fit the activity model.
 
@@ -121,14 +128,17 @@ is the loc subcommand, for example `status`, `diff`, `push`, or `create-page`.
 Shell commands that run more than one loc subcommand join the subcommands with
 `+`, for example `diff+status`. For non-loc shell calls, the detail is the
 executable name such as `git`, `gh`, `sed`, or `find`; for non-shell tools, it is
-the tool name such as `list_issues` or `API-post-search`.
+the tool name such as `list_issues` or `API-post-search`. Flattened viewer rows
+include the tool group in the command frame, for example
+`command:loc:diff+status` or `command:non_loc:git`.
 
 Harness metadata records, such as Claude terminal `result:success` records,
 `system:turn_duration`, `system:local_command`, attachments, file-history
-deltas, and hook summaries, are excluded from Perfetto traces, viewer profiles,
-and `totals_by_activity` because they can duplicate elapsed time that is already
-represented by user, assistant, reasoning, and tool spans. They are reported
-separately under `metadata` and in the Markdown `Excluded Metadata` section.
+deltas, and raw `harness.hook` summaries, are excluded from Perfetto traces,
+viewer profiles, and `totals_by_activity` because they can duplicate elapsed
+time that is already represented by user, assistant, reasoning, and tool spans.
+They are reported separately under `metadata` and in the Markdown
+`Excluded Metadata` section.
 
 ## Timing Model
 
@@ -142,6 +152,11 @@ record has a start timestamp but no duration, the script infers the end from
 the next timestamp in the same conversation. If there is no next timestamp, it
 uses `--default-duration-ms` or `1000ms`.
 
+For the Codex launch-readiness harness, live Codex hooks write `harness.phase`
+records during the running session. The modern profiler prefers those measured
+phase records for any activity bucket they cover and leaves the underlying raw
+Codex stream records in the audit-oriented kind and metadata summaries.
+
 Top-level wall time is computed from non-metadata event spans when any are
 present. Metadata timestamps can still act as run-boundary markers, but metadata
 durations do not extend wall time; this keeps terminal aggregate records from