Preview sessions
Let an agent hand a reviewer one immutable Candidate through a short-lived capability URL.
A delegated agent creates a read-only Preview handoff for one exact Candidate and returns the claimed URL to the reviewer. The rendered customer frontend, Candidate diff, later Approval when policy requires it, and execution all bind the same Candidate digest and immutable manifest hash. Published comparison uses ordinary Published delivery.
Candidate binding
The candidate_preview.create@1 operation carries the stable Backend, exact Environment, Candidate ID, Candidate digest, verified target, and optional paired entity/type route context. Supply both route IDs or neither:
{
"stableBackendId": "BACKEND_ID",
"environmentId": "ENVIRONMENT_ID",
"candidateId": "CANDIDATE_ID",
"candidateDigest": "64_CHARACTER_SHA256",
"entityId": "OPTIONAL_PAIRED_ENTITY_ID",
"typeId": "OPTIONAL_PAIRED_TYPE_ID",
"targetId": "TARGET_ID"
}Jetrepo rejects an unknown, expired, drifted, or digest-mismatched Candidate. It resolves the selected Environment’s exact physical generation, reads the Candidate materialization, and requires an enabled Verified target in that generation.
The successful Operation records only the session ID, ten-minute expiry, Candidate identifiers, manifest hash, perspective CANDIDATE, canEdit: false, and secretClaimAvailable: true. It does not retain the bootstrap code or review URL. The requesting agent claims the URL once with control_operation:CLAIM_SECRET and gives it to the reviewer.
Reviewer handoff
The review URL is a short-lived bearer capability, not a login page. Opening it displays a confirmation without consuming it. Confirmation posts the one-time code to the verified frontend, where the normal server-side exchange installs an opaque application cookie. The final website URL contains no Jetrepo credential.
The reviewer needs no Jetrepo account. Possession permits only read-only rendering of that Candidate on that target; it grants no Approval, execution, mutation, or publication authority. Ask the agent for a new URL after expiry, revocation, first exchange, Candidate change, or target change.
Agent access
The delegated agent needs:
operation.executeto propose and execute the handoff Operation;previewSession.createover the Candidate’s Backend and Environment;operation.readto claim the successful Operation’s one-time URL.
Jetrepo additionally checks the delegated authority’s operation.read, previewTarget.read, scoped previewSession.create, and content.read. The target and Candidate are looked up inside that scope, so an identifier from another tenant or Environment is indistinguishable from a missing resource.
Organization-owned unattended Agent keys do not create handoffs because session creation requires delegated human authority. Agent Auth and OAuth clients can do so without involving the governance console.
Live checks and provenance
Jetrepo rechecks session expiry/revocation, target state and origin, delegated authorization, exact Environment generation, Candidate digest and materialization, and the Candidate’s exact Draft base before use. If the live Draft head no longer matches the Candidate’s bound manifest ID and hash, Preview returns 409 CANDIDATE_DRIFT; the agent must reread Draft and propose again. A narrowed role, disabled target, changed generation, stale digest, or missing manifest also stops later requests.
Candidate responses are private/no-store and carry X-JetRepo-Candidate-Id, X-JetRepo-Candidate-Digest, X-JetRepo-Manifest-Id, and X-JetRepo-Manifest-Hash. These must match the Candidate provenance reported by the agent.
Do not combine a Delivery key and Preview Bearer. Preview is a bounded read context, not an editing bridge or unsaved-document channel.