The ReviewSession

Everything in cueloop renders, annotates, or resolves one noun: the ReviewSession. Get this primitive and the rest of the product follows.

A ReviewSession is an artifact plus a set of annotations, held in a workspace (a repo and branch context). The artifact is one of two shapes today:

• a plan - markdown an agent wrote before it starts work.
• a diff - unified-diff text for a set of file changes.

Pull-request review is planned as a third shape.

What a session holds

• the artifact - its type, its content, and metadata (the agent, the plan path, an optional pull-request reference the verdict can post back to).
• revisions - the artifact’s history. When the same agent session resubmits, the new content becomes a revision rather than a new session, so the review thread stays whole.
• annotations - quote-anchored notes on the artifact. See Annotations.
• a working copy - the reviewer’s own edits to a plan, which serialize as one unified diff against the submitted revision.
• a verdict - the reviewer’s decision, once resolved.

A session is pending until a verdict resolves it.

The verdict

A verdict is one of three kinds: comment, approve, or request_changes. Only approve lets an agent proceed; comment and request_changes both read as “do not proceed” in the agent contract.

The verdict carries a single structured markdown document, the feedback. cueloop builds it from the reviewer’s plan edits (applied first, verbatim) followed by every annotation, each located by its quoted text. Directive framing is deliberate: soft phrasing gets ignored by models.

Why a daemon

All session state lives in one local daemon behind a 0600 unix socket. Clients never touch session files; they render the session and send mutations over the socket. Because the daemon owns the wait, a verdict outlives the agent-side timeout - a review is never lost.