audit-cloud-sync

name	audit-cloud-sync
description	Audit Astra edge/cloud synchronization using local journals/checkpoints and current MatrixOne projection tables. Use for event ingestion gaps, restore/checkpoint mismatch, Work projection drift, and skill/learning visibility issues.
user_invocable	true
when_to_use	When the user wants to audit edge-cloud sync, event ingestion, restore behavior, checkpoint projection, task state, learning/preferences sync, or cloud/local data drift.
arguments	[{"name":"TARGET","description":"Session ID, run ID, Work ID, or 'last'. Omit for most recent session.","required":false},{"name":"ASPECT","description":"Audit focus: events, learning, checkpoints, work, skills, restore, or all. Default: all.","required":false}]
allowed_tools	["bash","read_file","grep","glob"]

Audit Cloud Sync

Audit current evidence, not a presumed sync diagram. Confirm the live schema and service owner first, then compare local artifacts with MatrixOne projections.

Task

$ARGUMENTS

Phase 1: Confirm Current Owners

Before querying data, confirm table names and owner modules from the repo:

rg -n "CREATE TABLE IF NOT EXISTS (agent_events|agent_sessions|session_checkpoints|run_checkpoints|user_preferences|skills_registry)" crates/services/src/storage.rs
rg -n "CREATE TABLE IF NOT EXISTS work_(items|branches|check_runs|acceptance_decisions|events|runtime_event_outbox)" crates/services/src/work.rs
rg -n "HybridRestoreService|RestoredSession|restore_recent_tools|session_checkpoints|run_checkpoints|learning_snapshots|skills_registry" crates/services crates/runtime crates/astra-cli --glob '!target/**'

Reference document when the issue involves restore, checkpoints, or skill paths: docs/architecture/edge-cloud-sync-architecture.md, especially section 8.

Important current facts:

• agent_events and agent_sessions are core projection tables.
• session_checkpoints stores session checkpoints; run_checkpoints stores run checkpoint payloads.
• work_items, work_branches, work_check_runs, and work_acceptance_decisions cover durable Work declaration and verification state.
• skills_registry is the database-backed skill catalog for web/runtime skills.
• user_preferences is current; session_sync_log is intentionally dropped in schema setup and must not be used as proof of current sync health.

Phase 2: Locate Local Evidence

Resolve the target:

ls -lt ~/.astra/sessions/*.jsonl 2>/dev/null | head
astra journal digest last --format json
astra journal digest <SESSION_ID> --format json
find ~/.astra/sessions/<SESSION_ID> -maxdepth 3 -type f | sort

Local evidence to collect:

Evidence	Path
Event stream	~/.astra/sessions/<session_id>.jsonl
Digest summary	astra journal digest <session_id> --format json
Step checkpoints	~/.astra/sessions/<session_id>/step_checkpoints/
Composite snapshot index	~/.astra/sessions/<session_id>/step_checkpoints/composite_snapshots.json
Local workspace restore metadata	~/.astra/sessions/<session_id>/workspace.yaml when present

Phase 3: Query Cloud Evidence Only When Configured

Use the project's configured MatrixOne connection. Do not hardcode database names; the service code resolves them through astra_core::resolve_database_name.

Suggested query dimensions:

Aspect	Tables / predicates
Events	agent_events by user_id, session_id, event_type, turn_id, run_id
Session projection	agent_sessions by user_id, session_id, event_count, status fields
Session checkpoints	session_checkpoints by user_id, session_id, number, turn
Run checkpoints	run_checkpoints by user_id, session_id, run_id, checkpoint_kind
Durable Work	work_items, work_branches, work_check_runs, work_acceptance_decisions, work_events
Skills	skills_registry plus runtime/API GET /skills path if testing web visibility
Preferences	user_preferences

If DB access is unavailable, produce a local-only audit and explicitly label cloud evidence as skipped.

Phase 4: Compare Invariants

Events:

• Local journal event count should explain agent_sessions.event_count; account for projection filtering before calling it loss.
• Critical trace events should appear in agent_events with owner-bound identity (user_id, event/run/session fields).
• Repeated local events missing in cloud usually indicate ingestion, ownership, or idempotency issues.

Checkpoints:

• Local checkpoint files and session_checkpoints should agree on session, turn, and summary/state availability.
• run_checkpoints should be used for run-scoped recovery, not confused with session rewind checkpoints.
• For restore bugs, compare astra_services::session_restore::RestoredSession with runtime step restore data; they are distinct layers.

Work:

• Work item revisions, check runs, acceptance decisions, and Work events must refer to compatible goal, graph, and criteria revisions.
• A delivered Work branch without current check and acceptance evidence is a Work lifecycle issue, not just sync lag.

Skills:

• Filesystem skills in .claude/skills or .agent/skills are local/catalog inputs.
• Web/runtime database-visible skills flow through skills_registry and capability selection.
• Do not assume a local filesystem skill is visible to remote runtime unless the code path loads that source.

Output Contract

Scope:
- target=<session/run/work>, aspect=<aspect>, mode=<local-only|local+cloud>

Evidence:
- local: <journal/checkpoint/digest facts>
- cloud: <table/query facts or skipped reason>

Mismatches:
- <only concrete mismatches with owner table/module>

Likely owner:
- <storage/service/runtime/cli file>

Next fix:
- <one actionable change or verification command>