flow-event-reader

Your objective is to correct background CocoPod completion timestamps from authoritative transcript queue records.

Inputs

Accept direct arguments or a queued request from .cocoplus/v2-runtime-requests.jsonl:

• transcript_path
• flow_state (default .cocoplus/lifecycle/flow-state.json)
• idempotency_key

Timestamp Precedence

Use transcript-derived completion records as the strongest source:

1. completed_at from a terminal transcript record
2. timestamp from a terminal transcript record
3. enqueued_at only when no completion timestamp exists
4. existing hook/tool-result timing as fallback

Do not overwrite transcript-derived timestamps with hook timing. If a pod already has completion_source: "enqueue_record" and completion_timestamp_reliable: true, preserve it unless a newer transcript record for the same pod has an explicit terminal completed_at.

Procedure

1. Read the existing flow-state JSON if present; otherwise start with { "pods": [] }.
2. Read the transcript JSONL line by line.
3. Identify queue/subagent completion records using named fields only:
   • subagent_id, pod_id, agent_id, or task_id
   • status, event, or type
   • completed_at, timestamp, or enqueued_at
4. For each terminal completion event (completed, failed, exited, cancelled), update the matching pod record:
   • completed_at
   • completion_source: "enqueue_record"
   • completion_timestamp_reliable: true
5. If a pod has only hook/tool-result timing, preserve it but mark:
   • completion_source: "tool_result_fallback"
   • completion_timestamp_reliable: false
6. Write flow_state atomically.

Queue Settlement

When invoked from .cocoplus/v2-runtime-requests.jsonl, follow execution-engine/runtime-queue:

1. Claim the request using idempotency_key or a derived key from transcript_path and flow_state.
2. Reconcile the flow-state file.
3. Append completed settlement with artifact: flow_state.
4. Append failed if the transcript cannot be read or flow_state cannot be written.

Output

Report:

CocoFlow completion events reconciled.
Pods corrected: <N>
Fallback records retained: <N>
Flow state: <path>

Exit Criteria

• Transcript-derived completion records set completion_source.
• Fallback records are explicitly marked unreliable.
• The flow-state file remains valid JSON.
• Queued requests are settled and can be replayed without duplicating state changes.

Anti-Rationalization

Shortcut / Temptation	Why It Fails
Treat the skill as complete because the file exists	Skill contracts must describe observable behavior and verification, not just command names.
Skip artifact and safety checks for a small command	Small commands still mutate state or guide execution; preserve the same gates.