feat(flow): add codex telemetry and workflow inspection

Add local-first Codex eval, telemetry, and trace inspection commands plus Maple export plumbing. Carry trace metadata through Flow-managed Codex routes, expose repo workflow overview over the local server, and document the operator surfaces.

The change is scoped for robustness and performance: local logs and memory remain canonical, export stays redacted and best-effort, codexd only does bounded background refresh/flush work, and env-store fallback lets Flow-managed sessions pick up shared Maple config without leaking repo-specific state.

Author: nikivdev

docs/codex-maple-telemetry-runbook.md

@@ -0,0 +1,109 @@
+# Codex Maple Telemetry Runbook
+
+Use this when you want shared analytics for Flow-guided Codex usage without
+changing the local source of truth.
+
+## What This Does
+
+Flow keeps Codex telemetry local first:
+
+- `codex/skill-eval/events.jsonl`
+- `codex/skill-eval/outcomes.jsonl`
+- Jazz2-backed Codex memory mirror
+
+Optional Maple export reads those local logs and emits a derived, redacted OTLP
+stream.
+
+What gets exported:
+
+- route / mode / action
+- runtime skill names and counts
+- prompt/context size metrics
+- reference counts
+- outcome kind / success
+- repo leaf name plus hashed path identifiers
+
+What does not get exported:
+
+- raw prompt text
+- full filesystem paths
+- raw session ids
+
+## Configure
+
+Use Flow env store so the daemon and Flow-launched Codex sessions see the same
+values. For local-only secrets, prefer the personal store:
+
+```bash
+cd ~/code/flow
+f env set --personal FLOW_CODEX_MAPLE_LOCAL_ENDPOINT=http://ingest.maple.localhost/v1/traces
+f env set --personal FLOW_CODEX_MAPLE_LOCAL_INGEST_KEY=maple_pk_local_xxx
+f env set --personal FLOW_CODEX_MAPLE_HOSTED_ENDPOINT=https://ingest.maple.dev/v1/traces
+f env set --personal FLOW_CODEX_MAPLE_HOSTED_INGEST_KEY=maple_sk_hosted_xxx
+f env set --personal FLOW_CODEX_MAPLE_HOSTED_PUBLIC_INGEST_KEY=maple_pk_hosted_xxx
+```
+
+Optional tuning:
+
+```bash
+f env set --personal FLOW_CODEX_MAPLE_SERVICE_NAME=flow-codex
+f env set --personal FLOW_CODEX_MAPLE_SCOPE_NAME=flow.codex
+f env set --personal FLOW_CODEX_MAPLE_ENV=local
+f env set --personal FLOW_CODEX_MAPLE_QUEUE_CAPACITY=1024
+f env set --personal FLOW_CODEX_MAPLE_MAX_BATCH_SIZE=64
+f env set --personal FLOW_CODEX_MAPLE_FLUSH_INTERVAL_MS=100
+f env set --personal FLOW_CODEX_MAPLE_CONNECT_TIMEOUT_MS=400
+f env set --personal FLOW_CODEX_MAPLE_REQUEST_TIMEOUT_MS=800
+```
+
+On macOS, personal env reads may require a daily unlock:
+
+```bash
+f env unlock
+```
+
+If you launch Codex through Flow (`j ...`, `f codex ...`, `k ...`), Flow will
+hydrate these `FLOW_CODEX_MAPLE_*` vars into the child Codex process. Explicit
+shell env vars override the personal store for that launch, which makes one-off
+telemetry tests quiet and deterministic.
+
+From inside a Codex session, the write path stays the same:
+
+```bash
+f env set --personal FLOW_CODEX_MAPLE_HOSTED_ENDPOINT=...
+f env set --personal FLOW_CODEX_MAPLE_HOSTED_INGEST_KEY=...
+f env get --personal FLOW_CODEX_MAPLE_HOSTED_ENDPOINT
+```
+
+## Run
+
+Inspect current state:
+
+```bash
+f codex telemetry status
+```
+
+Flush unseen local telemetry once:
+
+```bash
+f codex telemetry flush --limit 200
+```
+
+Equivalent task shortcuts:
+
+```bash
+f codex-telemetry-status
+f codex-telemetry-flush
+```
+
+## Background Export
+
+If `codexd` is running, it also performs a bounded background flush pass during
+its normal maintenance loop. This keeps export cheap and avoids a separate
+always-on process.
+
+## Notes
+
+- Export is derived and best-effort.
+- Local logs and memory stay canonical even if Maple is unavailable.
+- This is intended for route/context/outcome analytics, not transcript export.

docs/commands/ai.md

@@ -218,11 +218,17 @@ Codex usage history without replaying Codex in the hot path.
 Useful commands:
 
 ```bash
+f codex eval --path ~/work/example-project
 f codex memory sync --limit 400
 f codex memory recent --path ~/work/example-project --limit 12
 f codex skill-eval show --path ~/work/example-project
 f codex skill-eval run --path ~/work/example-project
 f codex skill-eval cron --limit 400 --max-targets 12 --within-hours 168
+f codex telemetry status
+f codex telemetry flush --limit 200
+f codex trace status
+f codex trace current-session --json
+f codex trace inspect <trace-id> --json
 f codex skill-source list --path ~/work/example-project
 f codex skill-source sync --path ~/work/example-project --skill find-skills
 ```
@@ -250,6 +256,76 @@ What `cron` does:
 
 For your use case, this keeps learning cheap and safe enough to run regularly.
 
+### Trace inspection for Flow-managed Codex sessions
+
+Flow now assigns a trace envelope to all Flow-managed Codex launches, not just
+special workflows like `check <github-pr-url>`.
+
+That means sessions started or resumed through:
+
+```bash
+j ...
+k <session-id>
+f codex open ...
+f codex resume ...
+f codex continue ...
+```
+
+carry `FLOW_TRACE_*` env vars and emit at least one compact Flow telemetry
+event, so the session becomes remotely inspectable.
+
+Useful commands:
+
+```bash
+f codex trace status
+f codex trace current-session --json
+f codex trace inspect <trace-id> --json
+```
+
+Behavior:
+
+- `trace status` checks whether Maple MCP reads are configured and reachable
+- `trace current-session` reads the active `FLOW_TRACE_ID` from the current
+  Flow-managed Codex session, flushes recent Flow telemetry once, then attempts
+  a remote trace read
+- if Maple reads are partially configured but tenant access is still blocked,
+  Flow returns the current trace metadata plus `readError` instead of failing
+  without context
+
+This keeps the workflow autonomous from inside Codex itself: once the session
+was started through Flow, you can inspect the current trace without manually
+copying ids.
+
+`f codex eval --path ...` is the joined operator report:
+
+- current runtime/doctor state
+- recent route mix and context cost
+- grounded skill scorecard highlights
+- concrete “what to improve next” recommendations
+- commands to deepen or fix the current state
+
+If `codexd` is running, it also keeps recent completion reconciliation warm and
+now does a bounded background scorecard refresh, so the eval report does not go
+stale as quickly between manual runs.
+
+Optional telemetry export follows the same local-first pattern: Flow keeps
+local Codex logs canonical, and if `FLOW_CODEX_MAPLE_*` env vars are set it can
+export redacted route/context/outcome spans to Maple without shipping raw
+prompts or full repo paths. Use:
+
+```bash
+f codex telemetry status
+f codex telemetry flush --limit 200
+```
+
+For local-only secrets, prefer `f env set --personal ...`. On macOS you may
+need `f env unlock` once per day for background reads. Flow-launched Codex
+sessions also inherit the same `FLOW_CODEX_MAPLE_*` values from the personal
+store, while explicit shell env still wins for one-off tests.
+
+When `codexd` is running, the daemon also performs a bounded background export
+pass so the external analytics view stays warm.
+
 ### macOS launchd schedule for skill-eval
 
 If you want scorecards to stay fresh automatically on macOS:

flow.toml

@@ -402,6 +402,16 @@ name = "codex-skill-eval-launchd-logs"
 command = "python3 ./scripts/codex-skill-eval-launchd.py logs $@"
 description = "Show scheduled Codex skill-eval launch agent logs"
 
+[[tasks]]
+name = "codex-telemetry-status"
+command = "f codex telemetry status $@"
+description = "Show optional redacted Codex telemetry export state"
+
+[[tasks]]
+name = "codex-telemetry-flush"
+command = "f codex telemetry flush $@"
+description = "Flush unseen redacted Codex telemetry to configured Maple endpoints once"
+
 [[tasks]]
 name = "test-args"
 command = "echo \"arg1=$1 arg2=$2 all=$@\""
@@ -496,6 +506,24 @@ variables = [
   { key = "FLOW_ROUTER_OVERRIDE_REASON", default = "" },
   { key = "FLOW_RL_SIGNAL_TEXT", default = "snippet" },
   { key = "FLOW_RL_SIGNAL_MAX_CHARS", default = "4000" },
+  { key = "FLOW_CODEX_MAPLE_LOCAL_ENDPOINT", default = "" },
+  { key = "FLOW_CODEX_MAPLE_LOCAL_INGEST_KEY", default = "" },
+  { key = "FLOW_CODEX_MAPLE_HOSTED_ENDPOINT", default = "" },
+  { key = "FLOW_CODEX_MAPLE_HOSTED_INGEST_KEY", default = "" },
+  { key = "FLOW_CODEX_MAPLE_HOSTED_PUBLIC_INGEST_KEY", default = "" },
+  { key = "FLOW_CODEX_MAPLE_TRACES_ENDPOINTS", default = "" },
+  { key = "FLOW_CODEX_MAPLE_INGEST_KEYS", default = "" },
+  { key = "FLOW_CODEX_MAPLE_SERVICE_NAME", default = "flow-codex" },
+  { key = "FLOW_CODEX_MAPLE_SERVICE_VERSION", default = "" },
+  { key = "FLOW_CODEX_MAPLE_SCOPE_NAME", default = "flow.codex" },
+  { key = "FLOW_CODEX_MAPLE_ENV", default = "local" },
+  { key = "FLOW_CODEX_MAPLE_QUEUE_CAPACITY", default = "1024" },
+  { key = "FLOW_CODEX_MAPLE_MAX_BATCH_SIZE", default = "64" },
+  { key = "FLOW_CODEX_MAPLE_FLUSH_INTERVAL_MS", default = "100" },
+  { key = "FLOW_CODEX_MAPLE_CONNECT_TIMEOUT_MS", default = "400" },
+  { key = "FLOW_CODEX_MAPLE_REQUEST_TIMEOUT_MS", default = "800" },
+  { key = "MAPLE_API_TOKEN", default = "" },
+  { key = "MAPLE_MCP_URL", default = "https://api.maple.dev/mcp" },
   { key = "SEQ_CH_MEM_PATH", default = "~/.config/flow/rl/seq_mem.jsonl" },
   { key = "HARBOR_DIR", default = "~/repos/laude-institute/harbor" },
 ]