Specs

Insights proxy naming (session user_messages ≠ human_turns)

Status built 2026-10-01 (honesty row #7).

All sections

Learn

  1. Getting started
  2. The outcome ladder
  3. The handoff
  4. Asks
  5. Forgotten context
  6. Suspect commits
  7. MCP setup
  8. Benchmarks
  9. The loop
  10. The governor

Reference

  1. CLI63
  2. HTTP API16
  3. MCP Tools19

Specs

  1. Agent bus
  2. App-merge P3 — parity / kill duplicates
  3. App-merge
  4. Archie bench
  5. Archie — the memory agents do not have
  6. Asks: a questions-to-answers index
  7. Beliefs
  8. Cache economics — what returning cold actually costs
  9. CLI grammar, completions, and the cockpit
  10. Codex human turns
  11. Compaction diff
  12. Compaction, and what it costs
  13. Context composition — what fills the window before the work does
  14. Convergence
  15. Desktop App — feasibility spec
  16. The done gate
  17. Dropped commitments
  18. Efficiency receipts
  19. The extension surface
  20. Fleet view
  21. Governor
  22. Handoff
  23. home latency: web deck vs terminal, measured
  24. home
  25. Insights proxy naming (session user_messages ≠ human_turns)
  26. Local search and the small-model angle
  27. Loop
  28. Loose ends
  29. Market map: observability that opens PRs
  30. MCP server
  31. Machine memory
  32. The questions worth answering
  33. The AgentWorth and SpacePilot loop
  34. Suspect commits
  35. Token accounting
  36. Trajectory scrubber
  37. Verified outcome rate
  38. Wake

Research

  1. All memos3

Changelog

  1. Every releasev0.1.28

The problem

Several /api/insights fields summed sessions.user_messages_count but were named as if they counted the human_turns table:

Old JSON field Actual SQL
volume.human_turns_index_proxy SUM(user_messages_count)
by_adapter[].human_turns per-adapter SUM(user_messages_count)
calls_per_turn_by_adapter[].human_turns same (calls/turn denominator)
top_sessions[].human_turns that session's user_messages_count

On a measured Codex slice, session user_messages can be thousands while human_turns rows from ~/.codex/history.jsonl are hundreds (SPEC #216 / #224). Colliding names made the proxy look like the table.

The real human_turns table feeds day_hour, friction, and vocabulary only.

Contract (schema_version 3)

Honest JSON field Deprecated alias (still emitted)
volume.session_user_messages volume.human_turns_index_proxy
by_adapter[].user_messages by_adapter[].human_turns
calls_per_turn_by_adapter[].user_messages …[].human_turns
top_sessions[].user_messages …[].human_turns

Semantics are unchanged — only names. Prefer the honest fields; aliases are for one tip cycle so existing readers do not break silently.

INSIGHTS_SCHEMA_VERSION is 3.

Non-goals

  • Changing the SQL or the human_turns ingest lane.
  • Removing aliases in the same PR that introduces the honest names.
  • Renaming day_hour / friction / vocabulary (those already read the real table).
  • Honesty matrix / detected vs indexed: docs/capability-matrix.md
  • Codex human turns: docs/specs/codex-human-turns.md

docs/specs/insights-proxy-naming.md on GitHub

Point it at your own machine.

npx -y agentworth@latest scan