agent-session-format-check

Agent Session Format Check

Answer one precise question for every supported agent:

Can current Agent Sessions code support the latest available session/storage/usage format from the latest available agent build?

The answer must be layered. Do not collapse version checks, stale samples, schema fingerprints, discovery contracts, and usage probes into a vague severity label.

Evidence-first:

• Gather a report + sample paths first.
• Do not change parsers/fixtures/docs without explicit user approval.

Related skill: agent-support-matrix — maintains the matrix YAML, ledger, and update-checklist workflow. This skill focuses on detection and evidence collection; agent-support-matrix focuses on recording and gating version bumps.

Process doc: docs/agent-support/monitoring.md — defines the compatibility verdicts, legacy severity model, cadence, and escalation workflow that feed into this skill.

---

1 Quick Start (all agents)

1. Run weekly monitoring:

   ./scripts/agent_watch.py --mode weekly
   

   Report path prints to stdout and is written under scripts/probe_scan_output/agent_watch/*/report.json.

2. In report.json, check each agent under results.<agent>:

   • compatibility.verdict, compatibility.scope, compatibility.blockers, and compatibility.next_action
   • verified_version, installed.parsed_version, upstream.parsed_version
   • compatibility.latest_status to distinguish current_fetch_known, cached_latest, and unknown latest-source states
   • weekly.local_schema (newest local session used for fingerprinting)
   • weekly.schema_diff and evidence.schema_matches_baseline
   • evidence.sample_freshness and evidence.fresh_evidence_source
   • compatibility.latest_real_session_failure when a prebump attempt failed
   • severity and recommendation only as legacy escalation fields

3. Usage / limits reading (Codex + Claude) — always verify every weekly run. These drift independently of session schema (see §2), so a clean schema does not imply healthy usage reading. Each agent's results.<agent>.weekly.probes is a list; for every relevant entry confirm ok == true and exit_code == 0:

   • Codex — label == "codex_status_probe" (parse codex_status_json): the active CLI status channel (five_hour, weekly percent-left). The passive channel is the session JSONL token_count / rate_limits events, covered by the schema fingerprint above.
   • Claude — label == "claude_usage_probe" (parse claude_usage_json): the authenticated /usage reading (session_5h, week_all_models, week_opus). Also label == "claude_status" (parse claude_status_json): status.claude.com indicator/incidents. A failed or unparsed usage probe is a usage-format or auth regression even when versions match and the session schema is clean — never skip it, and report each probe's ok explicitly rather than collapsing it into the compatibility verdict.