Recipes
Fourteen executable, state-aware journeys generated from schema-validated fixtures and the live MCP operation registry.
On this page
Start with Quickstart, then choose a recipe. Each recipe starts from a natural-language request and names its prerequisites and human boundary. The structured block is generated from a fixture whose tool names, complete inputs, representative outputs, output bindings, state transitions, terminal conditions, errors, and recovery paths are validated against the live registry.
Discover tools and prove read access
Use this at the beginning of every session. Live tools/list establishes capability; project_list and brief_list establish authentication and project reach. Configuration output alone is not readiness.
Prove that the configured MCP endpoint is authenticated, protocol-compatible, and exposes the capabilities needed for the task.
Requests you can make
- “Connect Semel to this agent.”
- “Check whether this Semel connection can run a local review.”
Prerequisites
Scopes: none
- MCP client configured or ready to configure
- Choose the intended Semel environment and authentication method.
Ordered steps
1. connect
Protocol action (connect): Connect to the configured Semel MCP URL.
Next: Classify connection failures separately from authentication failures.
2. authenticate
Protocol action (authenticate): Complete the harness-supported bearer-token or delegated OAuth flow.
Next: Request the live tools list only after authentication succeeds.
3. tools-list
Protocol action (tools_list): Read the actual MCP tools/list response.
Next: Compare the required capability names for the intended recipe.
4. compare-capabilities
Protocol action (compare_capabilities): Check names and protocol compatibility; never require an eternal tool count.
Next: Continue only when every required tool name is present.
Completion and recovery
Done when: The live server is authenticated and every capability required by the selected recipe is present.
- Repeat tools/list after reconnect or session reload.
- Negotiate protocol support separately from credential repair.
Errors
MCP_CLIENT_CONNECTION_FAILED: Transport setup cannot reach the configured endpoint. Verify the environment URL and network, then reconnect; do not relabel this as a login failure.MCP_CLIENT_CAPABILITY_MISSING: A required tool name is absent from tools/list. Stop, report the exact missing names, and refresh or upgrade the integration.
Never assume
- A successful login proves the MCP server is usable.
- The tool count is permanently fixed.
- A missing capability is an authentication failure.
Create a project for a new effort
First inspect existing projects for considerable overlap. A net-new effort normally gets one new project. Confirm the exact name before creation; an allowlisted principal cannot widen its own reach by creating a project.
Reuse an exact existing project or create one fresh project, then carry its structured project id.
Requests you can make
- “Create a project for checkout reliability.”
- “Find the checkout project and rename it to Payments reliability.”
Prerequisites
Scopes: brief:read, brief:write
- Authenticated agent with all-project creation access
- Resolve ambiguous project matches and explicitly confirm project creation, rename, and repository scope.
Ordered steps
1. project-list
When the preceding step succeeds and this call is allowed by the current server state.
project_list {}Structured result · project-list { "projects": [] }Result variant:
project-list. Read projects from structuredContent.projects.Next: Reuse one exact match, ask about ambiguity, or prepare project_create.
2. project-create
Only when no considerably overlapping project exists and the human explicitly confirms creation.
project_create { "name": "{{projectName}}", "reviewMode": "direct", "idempotencyKey": "{{idempotencyKey}}" }Structured result · project-created { "project": { "id": "prj_fixture_checkout", "workspaceId": "ws_fixture_primary", "name": "Checkout reliability", "reviewMode": "direct", "createdAt": "2026-09-07T16:00:00.000Z" } }Result variant:
project-created. Read projectId from structuredContent.project.id.Next: Carry project.id into every project-scoped call.
3. project-get
When the preceding step succeeds and this call is allowed by the current server state.
project_get { "projectId": "{{projectId}}" }Structured result · project { "project": { "id": "prj_fixture_checkout", "workspaceId": "ws_fixture_primary", "name": "Checkout reliability", "reviewMode": "direct", "createdAt": "2026-09-07T16:00:00.000Z" } }Result variant:
project. Read project from structuredContent.project.Next: Confirm the resolved project details before mutation.
4. project-rename
Only when the human requested and explicitly confirmed the rename.
project_rename { "projectId": "{{projectId}}", "name": "Payments reliability", "idempotencyKey": "{{idempotencyKey}}" }Structured result · project-renamed { "project": { "id": "prj_fixture_checkout", "workspaceId": "ws_fixture_primary", "name": "Payments reliability", "reviewMode": "direct", "createdAt": "2026-09-07T16:00:00.000Z" } }Result variant:
project-renamed. Read renamedProject from structuredContent.project.Next: Keep the same project id after the rename.
5. project-codebases-list
When the preceding step succeeds and this call is allowed by the current server state.
project_codebases_list { "projectId": "{{projectId}}", "limit": 50 }Structured result · codebase-inventory { "projectId": "prj_fixture_checkout", "codebases": [ { "repositoryId": "repo_fixture_throughline", "owner": "throughline", "name": "throughlineos", "trackingBranch": "main", "selected": false, "selectionStatus": "available" } ], "nextCursor": null }Result variant:
codebase-inventory. Read codebases from structuredContent.codebases.Next: Follow nextCursor until null before proposing repository scope.
6. project-codebase-link
Only after a human confirms one already-connected repository from the complete inventory.
project_codebase_link { "projectId": "{{projectId}}", "repositoryId": "{{repositoryId}}", "idempotencyKey": "{{idempotencyKey}}" }Structured result · codebase-linked { "projectCodebase": { "projectId": "prj_fixture_checkout", "repositoryId": "repo_fixture_throughline", "linked": true, "newlyLinked": true } }Result variant:
codebase-linked. Read linked from structuredContent.projectCodebase.linked.Next: Proceed with the confirmed repository in project scope.
Completion and recovery
Done when: One unambiguous project id is carried forward and any requested rename or repository link is reflected in the structured result.
- Repeat project_list before creating after an ambiguous or interrupted attempt.
- Use project_get to recover the canonical project after an idempotent replay.
Errors
PROJECT_ACCESS_DENIED: The principal cannot reach the resolved project. Stop and have an operator correct the project allowlist; never select another project silently.VALIDATION_FAILED: A project name, review mode, cursor, or repository id is invalid. Correct the field from live schema or inventory data and use a new mutation key for changed arguments.
Never assume
- A similar name is the intended project.
- Renaming requires creating another project.
- An unlisted or unconnected repository may be linked.
Create a brief from Linear issue content
Paste the issue content, or let a separately authorized harness fetch it. Semel does not expose a Linear-fetch tool. Confirm a brief-less project, then create one complete canonical brief without guessing an ID.
Turn user-supplied or connector-authorized issue text into a complete canonical brief in a resolved project.
Requests you can make
- “Create a brief from this pasted Linear issue.”
- “Use my authorized Linear connector to draft a brief for ENG-42.”
Prerequisites
Scopes: brief:read, brief:write
- Project id resolved
- Issue text pasted or fetched by a separate authorized connector
- Provide issue text or authorize the external Linear connector; Semel has no Linear-fetch tool.
- Explicitly confirm brief creation.
Ordered steps
1. supply-linear-text
Human action: Provide self-contained issue text or authorize a separate Linear connector to read it.
Next: Map the source into canonical brief sections without inventing missing requirements.
2. brief-create
When the preceding step succeeds and this call is allowed by the current server state.
brief_create { "projectId": "{{projectId}}", "title": "{{briefTitle}}", "content": { "goal": "Prevent duplicate charges when checkout retries.", "requirements": [ "Reuse one payment intent for retried submissions." ], "acceptanceCriteria": [ { "id": "AC-01", "text": "A retried request returns the original successful result." } ], "sourceArtifactLinks": [ { "label": "Linear ENG-42", "kind": "linear" } ] }, "idempotencyKey": "{{idempotencyKey}}" }Structured result · brief-created { "brief": { "id": "brf_fixture_checkout", "projectId": "prj_fixture_checkout", "title": "Retry-safe checkout", "state": "drafting", "currentVersionHash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "content": { "goal": "Prevent duplicate charges when checkout retries.", "requirements": [ "Reuse one payment intent for retried submissions." ], "acceptanceCriteria": [ { "id": "AC-01", "text": "A retried request returns the original successful result." } ], "sourceArtifactLinks": [ { "label": "Linear ENG-42", "kind": "linear" } ] }, "versionNum": 1 } }Result variant:
brief-created. Read briefId from structuredContent.brief.id.Next: Load the complete persisted aggregate by the returned brief id.
3. created-brief-get-full
When the preceding step succeeds and this call is allowed by the current server state.
brief_get_full { "briefId": "{{briefId}}" }Structured result · full-brief { "brief": { "id": "brf_fixture_checkout", "projectId": "prj_fixture_checkout", "title": "Retry-safe checkout", "state": "drafting", "currentVersionHash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "content": { "goal": "Prevent duplicate charges when checkout retries.", "requirements": [ "Reuse one payment intent for retried submissions." ], "acceptanceCriteria": [ { "id": "AC-01", "text": "A retried request returns the original successful result." } ], "sourceArtifactLinks": [ { "label": "Linear ENG-42", "kind": "linear" } ] }, "versionNum": 1 }, "collections": { "versions": { "items": [], "nextCursor": null }, "decisionHistory": { "items": [], "nextCursor": null }, "findings": { "items": [], "nextCursor": null }, "proposals": { "items": [], "nextCursor": null }, "approvals": { "items": [], "nextCursor": null }, "comments": { "items": [], "nextCursor": null }, "artifacts": { "items": [], "nextCursor": null }, "workOrders": { "items": [], "nextCursor": null }, "reviewSessions": { "items": [], "nextCursor": null }, "shares": { "items": [], "nextCursor": null } }, "gateNotificationStatus": null }Result variant:
full-brief. Read brief from structuredContent.brief.Next: Show the created brief and call out any source gaps for the human.
Completion and recovery
Done when: The structured result supplies a brief id and brief_get_full confirms the canonical persisted content.
- Retry an identical create with the same key.
- Use a new key only after materially changing the brief payload.
Errors
PROJECT_ACCESS_DENIED: The principal cannot reach the resolved project. Stop and have an operator correct the project allowlist; never select another project silently.VALIDATION_FAILED: The canonical brief payload rejects a field or value. Use only canonical section keys, preserve the supplied source facts, and validate the complete payload again.
Never assume
- Semel can fetch a Linear URL itself.
- Missing issue details may be fabricated.
- Free-form pseudo-sections are canonical brief keys.
Inspect a brief and its collections
brief_get_full returns the canonical content plus the first page of each collection. Continue paginating the needed collection instead of treating the first page as exhaustive.
Find a reachable brief, inspect its aggregate, and page one supported durable collection without inventing response fields.
Requests you can make
- “Show me the checkout brief.”
- “Inspect the decision history for this brief.”
Prerequisites
Scopes: brief:read
- Authenticated principal with project access
- Resolve ambiguous brief matches.
Ordered steps
1. brief-list
When the preceding step succeeds and this call is allowed by the current server state.
brief_list { "limit": 50 }Structured result · brief-list { "briefs": [ { "id": "brf_fixture_checkout", "projectId": "prj_fixture_checkout", "title": "Retry-safe checkout", "state": "drafting", "versionNum": 3, "updatedAt": "2026-09-07T16:00:00.000Z" } ], "nextCursor": null }Result variant:
brief-list. Read briefId from structuredContent.briefs[0].id.Next: Select an exact brief or ask the human to disambiguate.
2. brief-get-full
When the preceding step succeeds and this call is allowed by the current server state.
brief_get_full { "briefId": "{{briefId}}" }Structured result · full-brief { "brief": { "id": "brf_fixture_checkout", "projectId": "prj_fixture_checkout", "title": "Retry-safe checkout", "state": "drafting", "currentVersionHash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "content": { "goal": "Prevent duplicate charges when checkout retries.", "requirements": [ "Reuse one payment intent for retried submissions." ], "acceptanceCriteria": [ { "id": "AC-01", "text": "A retried request returns the original successful result." } ], "sourceArtifactLinks": [ { "label": "Linear ENG-42", "kind": "linear" } ] }, "versionNum": 3 }, "collections": { "versions": { "items": [], "nextCursor": null }, "decisionHistory": { "items": [], "nextCursor": null }, "findings": { "items": [], "nextCursor": null }, "proposals": { "items": [], "nextCursor": null }, "approvals": { "items": [], "nextCursor": null }, "comments": { "items": [], "nextCursor": null }, "artifacts": { "items": [], "nextCursor": null }, "workOrders": { "items": [], "nextCursor": null }, "reviewSessions": { "items": [], "nextCursor": null }, "shares": { "items": [], "nextCursor": null } }, "gateNotificationStatus": null }Result variant:
full-brief. Read collections from structuredContent.collections.Next: Read collection summaries/pages from collections rather than invented top-level arrays.
3. brief-collection-list
When the preceding step succeeds and this call is allowed by the current server state.
brief_collection_list { "briefId": "{{briefId}}", "collection": "decisionHistory", "limit": 50 }Structured result · collection-page { "collection": "decisionHistory", "items": [], "nextCursor": null }Result variant:
collection-page. Read nextCursor from structuredContent.nextCursor.Next: Repeat with the returned cursor until nextCursor is null.
Completion and recovery
Done when: The requested aggregate is shown and every requested collection page has nextCursor equal to null.
- Restart pagination from no cursor if a cursor is rejected after data changes.
Errors
PROJECT_ACCESS_DENIED: The principal cannot reach the resolved project. Stop and have an operator correct the project allowlist; never select another project silently.VALIDATION_FAILED: The collection name or pagination arguments are invalid. Choose an advertised collection enum and reuse only the opaque returned cursor.
Never assume
- Collections are top-level arrays on brief_get_full.
- A single page is the complete collection when nextCursor is non-null.
- Cursors may be constructed locally.
Add a version by updating a brief
Read the current full content and carry forward every section you want to retain. brief_update is full replacement, including arrays, and creates a new immutable version. Resolve BRIEF_VERSION_CONFLICT by rereading before proposing a new replacement.
Replace complete brief content with a guarded new version or toggle one checklist row atomically.
Requests you can make
- “Add the retry acceptance criterion to this brief.”
- “Check off the API contract QA item.”
Prerequisites
Scopes: brief:read, brief:write
- Current full brief and version number loaded
- Explicitly confirm the complete-content replacement.
Ordered steps
1. update-source-get-full
When the preceding step succeeds and this call is allowed by the current server state.
brief_get_full { "briefId": "{{briefId}}" }Structured result · full-brief { "brief": { "id": "brf_fixture_checkout", "projectId": "prj_fixture_checkout", "title": "Retry-safe checkout", "state": "drafting", "currentVersionHash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "content": { "goal": "Prevent duplicate charges when checkout retries.", "requirements": [ "Reuse one payment intent for retried submissions." ], "acceptanceCriteria": [ { "id": "AC-01", "text": "A retried request returns the original successful result." } ], "sourceArtifactLinks": [ { "label": "Linear ENG-42", "kind": "linear" } ], "checklist": [ { "text": "API contract reviewed", "checked": false } ] }, "versionNum": 3 }, "collections": { "versions": { "items": [], "nextCursor": null }, "decisionHistory": { "items": [], "nextCursor": null }, "findings": { "items": [], "nextCursor": null }, "proposals": { "items": [], "nextCursor": null }, "approvals": { "items": [], "nextCursor": null }, "comments": { "items": [], "nextCursor": null }, "artifacts": { "items": [], "nextCursor": null }, "workOrders": { "items": [], "nextCursor": null }, "reviewSessions": { "items": [], "nextCursor": null }, "shares": { "items": [], "nextCursor": null } }, "gateNotificationStatus": null }Result variant:
full-brief. Read currentContent from structuredContent.brief.content.Next: Apply the requested edit locally while preserving every untouched key.
2. brief-update
When the preceding step succeeds and this call is allowed by the current server state.
brief_update { "briefId": "{{briefId}}", "title": "{{briefTitle}}", "content": { "goal": "Prevent duplicate charges when checkout retries.", "requirements": [ "Reuse one payment intent for retried submissions." ], "acceptanceCriteria": [ { "id": "AC-01", "text": "A retried request returns the original successful result." }, { "id": "AC-02", "text": "The response identifies the original payment intent." } ], "checklist": [ { "text": "API contract reviewed", "checked": false } ], "sourceArtifactLinks": [ { "label": "Linear ENG-42", "kind": "linear" } ] }, "ifVersionNum": 3, "idempotencyKey": "{{idempotencyKey}}" }Structured result · brief-updated { "brief": { "id": "brf_fixture_checkout", "projectId": "prj_fixture_checkout", "title": "Retry-safe checkout", "state": "drafting", "currentVersionHash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "content": { "goal": "Prevent duplicate charges when checkout retries.", "requirements": [ "Reuse one payment intent for retried submissions." ], "acceptanceCriteria": [ { "id": "AC-01", "text": "A retried request returns the original successful result." }, { "id": "AC-02", "text": "The response identifies the original payment intent." } ], "checklist": [ { "text": "API contract reviewed", "checked": false } ], "sourceArtifactLinks": [ { "label": "Linear ENG-42", "kind": "linear" } ] }, "versionNum": 4, "createdNewVersion": true, "staledApprovals": 0 } }Result variant:
brief-updated. Read versionNum from structuredContent.brief.versionNum.Next: Inspect createdNewVersion and the returned current version.
3. brief-checklist-update
Only when the user requested a single checklist toggle and the exact row text/version are known.
brief_checklist_update { "briefId": "{{briefId}}", "index": 0, "expectedText": "API contract reviewed", "checked": true, "ifVersionNum": 4, "idempotencyKey": "{{idempotencyKey}}" }Structured result · checklist-toggled { "brief": { "id": "brf_fixture_checkout", "projectId": "prj_fixture_checkout", "title": "Retry-safe checkout", "state": "drafting", "currentVersionHash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "content": { "goal": "Prevent duplicate charges when checkout retries.", "requirements": [ "Reuse one payment intent for retried submissions." ], "acceptanceCriteria": [ { "id": "AC-01", "text": "A retried request returns the original successful result." }, { "id": "AC-02", "text": "The response identifies the original payment intent." } ], "sourceArtifactLinks": [ { "label": "Linear ENG-42", "kind": "linear" } ], "checklist": [ { "text": "API contract reviewed", "checked": true } ] }, "versionNum": 5, "createdNewVersion": true, "staledApprovals": 0 } }Result variant:
checklist-toggled. Read checklistVersionCreated from structuredContent.brief.createdNewVersion.Next: Use this atomic result instead of replacing the full checklist.
Completion and recovery
Done when: The returned brief reports the intended version/content state and the requested checklist row is correct.
- Replay an identical mutation with the same idempotency key.
- Never reuse a key after changing content or version guards.
Errors
BRIEF_VERSION_CONFLICT: ifVersionNum is no longer current. Re-read the full brief, reconcile the human change, and submit materially updated arguments with a new mutation key.PROJECT_ACCESS_DENIED: The principal cannot reach the resolved project. Stop and have an operator correct the project allowlist; never select another project silently.
Never assume
- brief_update is a partial patch.
- A checklist tick should overwrite the whole checklist.
- A stale version can be forced through.
Export a verified brief package
Use the package export for a durable implementation handoff. It is a billable write requiring brief:write; bind to the exact current version and consume only the returned artifact resource link.
Create and retrieve the canonical verified package, using Markdown only as an explicitly legacy compatibility export.
Requests you can make
- “Export this brief for implementation.”
- “Give me the legacy Markdown export for compatibility.”
Prerequisites
Scopes: brief:read, brief:write
- Brief is ready for implementation handoff
- Explicitly confirm minting the immutable package.
Ordered steps
1. brief-export-package
When the preceding step succeeds and this call is allowed by the current server state.
brief_export_package { "briefId": "{{briefId}}", "idempotencyKey": "{{idempotencyKey}}" }Structured result · ready { "exportId": "example", "status": "ready", "filename": "retry-safe-checkout.zip", "downloadUrl": "https://mcp.semel.ai/brief-exports/exp_fixture_checkout", "manifestSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "implementationReady": true, "expiresAt": "2026-09-07T16:00:00.000Z", "snapshotId": "example", "contractVersionId": "example" }Result variant:
ready. Read downloadUrl from structuredContent.downloadUrl.Next: Fetch the bearer-authenticated resource before expiresAt and verify the manifest/hash.
2. download-package
Protocol action (download_resource): Download the returned resource_link with the same authorized agent context.
Next: Verify content and record expiry rather than treating a URL as permanent.
3. brief-export-markdown
Only when the human explicitly needs the legacy Markdown compatibility format.
brief_export_markdown { "briefId": "{{briefId}}" }Structured result · legacy-markdown { "filename": "retry-safe-checkout.zip", "resource": { "uri": "https://mcp.semel.ai/brief-exports/brf_fixture_checkout.md", "name": "retry-safe-checkout.md", "mimeType": "text/markdown" }, "downloadUrl": "example", "markdown": "example" }Result variant:
legacy-markdown. Read legacyResource from structuredContent.resource.Next: Label the result deprecated and do not treat it as a verified handoff.
Completion and recovery
Done when: A ready, implementationReady package is verified and downloaded, or the explicitly requested legacy export is clearly labelled.
- Repeat an identical package mutation with the same key.
- Mint a new package only after the brief or export request changes.
Errors
PAYLOAD_REJECTED: The package cannot be verified or is blocked. Stop; resolve the reported brief/package defect and mint a new package rather than falling back silently.PROJECT_ACCESS_DENIED: The principal cannot reach the resolved project. Stop and have an operator correct the project allowlist; never select another project silently.
Never assume
- A failed package can be replaced by Markdown without disclosure.
- A download URL never expires.
- Receiving a URL proves its bytes passed verification.
Originate and observe a review
Choose hosted or local dispatch intent when starting the review. This originates work against a pinned brief; it does not reconfigure the cascade, approve a gate, or grant local execution.
Start the first or a later review pass with an explicit execution choice, observe live dispatch, and cancel only an agent-originated run when requested.
Requests you can make
- “Run a hosted review of this brief.”
- “Start another local review pass from the last completed run.”
- “Cancel the review you just started.”
Prerequisites
Scopes: brief:read, review:run, review:execute
- Project reviewer configuration completed in the portal
- Brief id resolved
- Configure reviewer/provider/model in the portal.
- Confirm the target, execution mode, and spend-bearing start or cancellation.
Ordered steps
1. configure-reviewers
Human action: Configure the project reviewer cascade and provider/model choices in the Semel portal.
Next: Return to the agent after the portal confirms configuration.
2. review-start
When the preceding step succeeds and this call is allowed by the current server state.
review_start { "briefId": "{{briefId}}", "execution": "hosted", "idempotencyKey": "{{idempotencyKey}}" }Structured result · hosted-start { "run": { "id": "run_fixture_review", "status": "queued", "position": 0 }, "cascade": { "projectId": "prj_fixture_checkout", "phase": "reviewing" }, "dispatch": { "status": "invoking", "admitted": true, "softCapWarning": false } }Result variant:
hosted-start. Read runId from structuredContent.run.id.Next: Poll review_status and respect configless, cap, evidence-wait, or in-flight outcomes.
3. review-status
When the preceding step succeeds and this call is allowed by the current server state.
review_status { "briefId": "{{briefId}}" }Structured result · review-status { "projectId": "prj_fixture_checkout", "phase": "complete", "inFlight": false, "execution": "hosted", "awaitingLocalClaim": false, "steps": [], "latestRunId": "run_fixture_review", "latestTerminalRunId": "run_fixture_review", "blocked": null }Result variant:
review-status. Read latestRunId from structuredContent.latestRunId; anchorRunId from structuredContent.latestTerminalRunId.Next: Use latestTerminalRunId as the anchor for a later pass only when the user asks.
4. review-new-pass
Only for a requested later pass anchored to a real terminal run; local execution additionally requires review:execute.
review_new_pass { "briefId": "{{briefId}}", "anchorRunId": "{{anchorRunId}}", "execution": "local", "idempotencyKey": "{{idempotencyKey}}" }Structured result · local-start { "run": { "id": "run_fixture_followup", "status": "queued", "position": 0 }, "cascade": { "projectId": "prj_fixture_checkout", "phase": "reviewing" }, "dispatch": { "status": "awaiting_local_claim", "admitted": true, "softCapWarning": false } }Result variant:
local-start. Read newRunId from structuredContent.run.id.Next: Request the returned local session grant; do not claim without approval.
5. review-cancel
Only after explicit confirmation and only for a run this agent originated.
review_cancel { "runId": "{{newRunId}}", "idempotencyKey": "{{idempotencyKey}}" }Structured result · cancel-requested { "runId": "run_fixture_followup", "outcome": "cancel_requested", "status": "queued" }Result variant:
cancel-requested. Read cancelOutcome from structuredContent.outcome.Next: Stop local work and follow the authoritative returned status.
Completion and recovery
Done when: The requested pass has a returned run id and observable status, or cancellation reaches the authoritative returned outcome.
- Use review_status after any ambiguous transport outcome.
- Replay identical start/cancel requests with their original mutation key.
Errors
RUN_ALREADY_TERMINAL: Cancellation targets a run that already settled. Accept the terminal status and do not retry cancellation.VALIDATION_FAILED: Review configuration, anchor, or execution request is invalid. Inspect review_status and have the human repair portal configuration or select a valid terminal anchor.
Never assume
- Checkpoints or heartbeat configure reviewers.
- A later pass needs no terminal anchor.
- The agent may cancel a human- or other-agent-originated run.
Select the next review pass or cancel safely
Inspect status before choosing a legal agent action such as a new pass or cancellation. Cascade configuration, destructive clear/restart, and human gate decisions remain in the Semel UI.
Inspect review state and direct the human to the actual portal configuration surface without inventing an MCP configuration API.
Requests you can make
- “Change the engineering reviewer model.”
- “Configure this project for a security review.”
Prerequisites
Scopes: brief:read, review:run
- Project and brief resolved
- Select reviewer, provider, model, and configuration in the portal.
Ordered steps
1. configuration-review-status
When the preceding step succeeds and this call is allowed by the current server state.
review_status { "briefId": "{{briefId}}" }Structured result · review-status { "projectId": "prj_fixture_checkout", "phase": "reviewing", "inFlight": false, "execution": "hosted", "awaitingLocalClaim": false, "steps": [], "latestRunId": "example", "latestTerminalRunId": "example", "blocked": null }Result variant:
review-status. Read phase from structuredContent.phase.Next: Explain the current state and the exact human portal action.
2. portal-review-configuration
Human action: Open project review settings and select/update the reviewer, provider, model, and supported configuration.
Next: Wait for the portal to report a saved configuration before starting a review.
Completion and recovery
Done when: The human confirms the actual portal configuration is saved and a fresh review_status reflects an eligible state.
- Re-read review_status after the human changes settings.
Errors
AUTHORIZATION_SCOPE_MISSING: The current principal cannot inspect review state. Have an operator grant the minimum read/run scope or inspect the state directly in the portal.
Never assume
- Heartbeat, sync, or checkpoints update reviewer configuration.
- A nonexistent reviewer configuration tool may be called.
- The agent may choose provider consent or BYOK secrets for the human.
Drive one local execution session
Tell the human up front that each cascade step needs its own approved execution grant. Request a grant, wait for human approval, claim one eligible step, fetch its exact pinned skill, heartbeat and checkpoint under the current fence, then submit or release.
Follow a human-approved local execution grant through pinned artifact retrieval, fenced progress, sync/heartbeat, submit, or an explicit pre-submit handoff.
Requests you can make
- “Run this eligible review session in my local harness.”
- “Hand this local review session to another harness.”
- “Complete and submit the current local engineering review.”
Prerequisites
Scopes: brief:read, review:execute
- Eligible local review session exists
- No local execution is currently assumed
- Approve the execution grant returned by Semel.
- Choose completion versus pre-submit handoff.
Ordered steps
1. execution-grant-request
When the preceding step succeeds and this call is allowed by the current server state.
review_execution_grant_request { "reviewSessionId": "{{reviewSessionId}}" }Structured result · approval-required { "status": "approval_required", "approvalUri": "https://mcp.semel.ai/review-execution/approve/xgr_fixture_engineering", "pollHandle": "poll_fixture_engineering", "controlBlock": { "state": { "sessionState": "awaiting_executor", "protocolVersion": "1.1" }, "allowedNextOperations": [ { "operation": "review_execution_claim", "preconditions": [ "An operator-issued grant already exists; any authorized claimant may claim it." ] }, { "operation": "review_execution_status", "preconditions": [ "Always callable as the documented fail-safe." ] } ], "completion": { "complete": false, "unmetRequirements": [], "certificateState": "not_applicable" }, "progress": { "checkpointHighWaterMark": 0, "openQuestionCount": 0, "leaseExpiresAt": "2026-09-07T16:15:00.000Z", "suggestedPollAt": "2026-09-07T16:05:00.000Z" }, "operatorAction": { "required": true, "uri": "https://mcp.semel.ai/review-execution/approve/xgr_fixture_engineering" } } }Result variant:
approval-required. Read approvalUri from structuredContent.approvalUri.Next: Show approvalUri to the human and poll only as instructed.
2. approve-execution-grant
Human action: A verified human opens the returned approval URI and approves the exact session/harness intent.
Next: Resume only after grant_request returns ready with a real grant id.
3. execution-claim
When the preceding step succeeds and this call is allowed by the current server state.
review_execution_claim { "grantId": "{{grantId}}", "reviewSessionId": "{{reviewSessionId}}", "supportedProtocolVersions": [ "{{protocolVersion}}" ], "harnessDescriptor": { "harness": "codex", "harnessVersion": "1", "agent": "codex", "model": "gpt-5" }, "idempotencyKey": "{{idempotencyKey}}" }Structured result · claimed { "bundle": { "protocolVersion": "1.1", "instructions": "Semel external-execution protocol v1: after review_execution_claim pins this bundle, the active skill is exactly one at a time (see the frozen skill order). Fetch the active reviewer lens and its matching shared framing with review_execution_skill_get. Use review_execution_checkpoint_append for bounded semantic milestones, review_question_open/review_question_answer for durable questions, review_execution_sync to discover recorded answers/cancellation/handoff without a persistent session, review_execution_heartbeat to renew the current fenced epoch, and review_execution_submit to finalize against this exact pinned brief base. review_execution_status is always callable and is the documented fail-safe whenever local context is lost. Raw chain-of-thought, source dumps, and hidden reasoning are never accepted fields.", "schemaHashes": { "review_execution_grant_request": "e52e7b64d1f1249e1e92c230fe31d7ac8aa504b9e00b154669269ee819d0ce08", "review_execution_claim": "a124f54e50215258b0b669806e5278f5fcf4a9a1dd9c5501f2cff7ac99345ed7", "review_execution_skill_get": "fbc91868b45920f159c6e65eccc70fe8d2a5bd107dbece3cceb4f8bf7edaf12c", "review_execution_checkpoint_append": "023d0a5c99799ffd1734b9ff5c37da0391ab3a80beba895522ee824a171058ad", "review_question_open": "2304a9fc9feed0e54f96202864f313485028d63f11d9c5bea41bbd8af6ceac2b", "review_question_answer": "cd82c71b9090d96c9b972b89d22baac83167073503cf06d0efd0eada62e2ba8b", "review_question_answer_supersede": "8ca9bcface0a212deb4c6595d162fffb06089c278177234ea995228e85277904", "review_execution_sync": "e3228cdf437c31d501474f2d688e25968a40bce0f1a620000cb8bb0840003907", "review_execution_heartbeat": "b9ed5d743c1a9f668eb4ba3a4cc57552fc625fe115175906b4999fb3afbab4f3", "review_execution_release": "c22b0fc25aa734487b075da1d665b75c9b645dbfbaca7b673863d942fbb58fe5", "review_execution_submit": "80e9035b5dd37421bbdb6535042b7c2501bdcfd17e42070beb7a83ff1af3235f", "review_execution_status": "1b27dee7128f1cec0c9c3bab65ea2368b58427a60728a156a0260e84f0c5edc4", "project_context_sources_list": "662b917601c66ad54d599da31eba19a3bfa149f4b9ae36d0761a8e920206af35", "project_context_search": "463c91ced23d7d9578b00661eed0e9bc14648f3c42fe70bee3a700ab4faeb0f3", "project_context_evidence_get": "7c491de307d0624711916c3ba22c3a98635554e4b3654fba07700dce2d5965a0" }, "session": { "reviewSessionId": "rs_fixture_engineering", "runId": "run_fixture_review", "projectId": "prj_fixture_checkout", "briefId": "brf_fixture_checkout", "reviewMode": "direct", "reviewerSet": [ "engineering" ], "cascadeStepId": "step_fixture_engineering" }, "briefBase": { "versionId": "bv_fixture_checkout_v3", "versionNum": 3, "sha256": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc" }, "skills": [ { "role": "engineering", "version": "1", "sha256": "182b9a93e2b09a21a9cd632254e97f9dcb7582f34a50c2619588f75edde15dc7", "framingHash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" }, { "role": "reviewer-protocol-framing", "version": "1", "sha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "framingHash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" } ], "evidencePolicy": {}, "requiredCheckpoints": [ "skill_start", "evidence_readiness_change", "question_wait_enter", "question_wait_exit", "validation_start", "validation_result", "submit" ], "limits": { "checkpointMaxBytes": 65536, "summaryMaxBytes": 8192, "sessionEventBudgetBytes": 10485760 } }, "canonicalBundleSha256": "c45cacf945339d19f0d3f1f4a7e7977071f9555780cdd79b0ce1768decdfbd90", "envelope": { "executionId": "xex_fixture_engineering", "fenceGeneration": 1, "leaseExpiresAt": "2026-09-07T16:15:00.000Z", "heartbeatRecommendedSeconds": 30, "harnessDescriptor": { "harness": "codex", "harnessVersion": "1", "agent": "codex", "model": "gpt-5" } }, "activeSkill": { "role": "engineering", "cursor": "sync_fixture_next" }, "controlBlock": { "state": { "sessionState": "claimed", "protocolVersion": "1.1" }, "allowedNextOperations": [ { "operation": "review_execution_skill_get", "preconditions": [ "Awaiting the first checkpoint, which advances the epoch into running." ] }, { "operation": "review_execution_checkpoint_append", "preconditions": [ "Awaiting the first checkpoint, which advances the epoch into running." ] }, { "operation": "review_execution_heartbeat", "preconditions": [ "Awaiting the first checkpoint, which advances the epoch into running." ] }, { "operation": "review_execution_release", "preconditions": [ "Awaiting the first checkpoint, which advances the epoch into running." ] }, { "operation": "review_execution_status", "preconditions": [ "Always callable as the documented fail-safe." ] } ], "completion": { "complete": false, "unmetRequirements": [], "certificateState": "not_applicable" }, "progress": { "checkpointHighWaterMark": 0, "openQuestionCount": 0, "leaseExpiresAt": "2026-09-07T16:15:00.000Z", "suggestedPollAt": "2026-09-07T16:05:00.000Z" }, "operatorAction": { "required": false } } }Result variant:
claimed. Read executionId from structuredContent.envelope.executionId; canonicalBundleSha256 from structuredContent.canonicalBundleSha256.Next: Persist executionId, fenceGeneration, bundle hash, lease guidance, and activeSkill from structuredContent.
4. execution-skill-get
When the preceding step succeeds and this call is allowed by the current server state.
review_execution_skill_get { "executionId": "{{executionId}}", "role": "engineering" }Structured result · active-skill { "artifact": { "role": "engineering", "version": "1", "sha256": "182b9a93e2b09a21a9cd632254e97f9dcb7582f34a50c2619588f75edde15dc7", "framingHash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "contentType": "text/markdown", "bytes": "# Engineering review\n\nValidate the brief against the repository evidence." } }Result variant:
active-skill. Read skillSha256 from structuredContent.artifact.sha256.Next: Verify exact pinned hash/framing and execute only the active skill bytes.
5. execution-checkpoint-skill-start
When the preceding step succeeds and this call is allowed by the current server state.
review_execution_checkpoint_append { "executionId": "{{executionId}}", "fenceGeneration": 1, "seq": 1, "activeSkillId": "engineering", "milestoneName": "skill_start", "safeSummary": "Started the pinned engineering skill.", "receipt": { "skillRole": "engineering", "skillSha256": "{{skillSha256}}" }, "clientObservedAt": "2026-09-07T16:00:00.000Z", "idempotencyKey": "{{idempotencyKey}}" }Structured result · checkpoint-accepted { "accepted": true, "seq": 1, "highWaterMark": 1, "suggestedNextPollAt": "2026-09-07T16:05:00.000Z", "coalesce": false, "controlBlock": { "state": { "sessionState": "running", "protocolVersion": "1.1" }, "allowedNextOperations": [ { "operation": "review_execution_skill_get", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_checkpoint_append", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_heartbeat", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_question_open", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_submit", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_release", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_sync", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_status", "preconditions": [ "Always callable as the documented fail-safe." ] } ], "completion": { "complete": false, "unmetRequirements": [], "certificateState": "not_applicable" }, "progress": { "checkpointHighWaterMark": 1, "openQuestionCount": 0, "leaseExpiresAt": "2026-09-07T16:15:00.000Z", "suggestedPollAt": "2026-09-07T16:05:00.000Z" }, "operatorAction": { "required": false } } }Result variant:
checkpoint-accepted. Read checkpoint1HighWaterMark from structuredContent.highWaterMark.Next: Inspect evidence readiness before drawing conclusions.
6. execution-checkpoint-evidence
When the preceding step succeeds and this call is allowed by the current server state.
review_execution_checkpoint_append { "executionId": "{{executionId}}", "fenceGeneration": 1, "seq": 2, "activeSkillId": "engineering", "milestoneName": "evidence_readiness_change", "safeSummary": "Required repository evidence is ready.", "receipt": { "evidenceReady": true }, "clientObservedAt": "2026-09-07T16:00:00.000Z", "idempotencyKey": "{{idempotencyKey}}" }Structured result · checkpoint-accepted { "accepted": true, "seq": 2, "highWaterMark": 2, "suggestedNextPollAt": "2026-09-07T16:05:00.000Z", "coalesce": false, "controlBlock": { "state": { "sessionState": "running", "protocolVersion": "1.1" }, "allowedNextOperations": [ { "operation": "review_execution_skill_get", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_checkpoint_append", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_heartbeat", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_question_open", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_submit", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_release", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_sync", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_status", "preconditions": [ "Always callable as the documented fail-safe." ] } ], "completion": { "complete": false, "unmetRequirements": [], "certificateState": "not_applicable" }, "progress": { "checkpointHighWaterMark": 2, "openQuestionCount": 0, "leaseExpiresAt": "2026-09-07T16:15:00.000Z", "suggestedPollAt": "2026-09-07T16:05:00.000Z" }, "operatorAction": { "required": false } } }Result variant:
checkpoint-accepted. Read checkpoint2HighWaterMark from structuredContent.highWaterMark.Next: Begin validation against the pinned brief and evidence.
7. execution-checkpoint-validation-start
When the preceding step succeeds and this call is allowed by the current server state.
review_execution_checkpoint_append { "executionId": "{{executionId}}", "fenceGeneration": 1, "seq": 3, "activeSkillId": "engineering", "milestoneName": "validation_start", "safeSummary": "Running the bounded validation pass.", "receipt": { "validationStarted": true }, "clientObservedAt": "2026-09-07T16:00:00.000Z", "idempotencyKey": "{{idempotencyKey}}" }Structured result · checkpoint-accepted { "accepted": true, "seq": 3, "highWaterMark": 3, "suggestedNextPollAt": "2026-09-07T16:05:00.000Z", "coalesce": false, "controlBlock": { "state": { "sessionState": "running", "protocolVersion": "1.1" }, "allowedNextOperations": [ { "operation": "review_execution_skill_get", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_checkpoint_append", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_heartbeat", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_question_open", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_submit", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_release", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_sync", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_status", "preconditions": [ "Always callable as the documented fail-safe." ] } ], "completion": { "complete": false, "unmetRequirements": [], "certificateState": "not_applicable" }, "progress": { "checkpointHighWaterMark": 3, "openQuestionCount": 0, "leaseExpiresAt": "2026-09-07T16:15:00.000Z", "suggestedPollAt": "2026-09-07T16:05:00.000Z" }, "operatorAction": { "required": false } } }Result variant:
checkpoint-accepted. Read checkpoint3HighWaterMark from structuredContent.highWaterMark.Next: Run the reviewer checks and retain only bounded result facts.
8. execution-checkpoint-validation-result
When the preceding step succeeds and this call is allowed by the current server state.
review_execution_checkpoint_append { "executionId": "{{executionId}}", "fenceGeneration": 1, "seq": 4, "activeSkillId": "engineering", "milestoneName": "validation_result", "safeSummary": "Validation completed with no blocking findings.", "receipt": { "validationPassed": true, "findingCount": 0 }, "clientObservedAt": "2026-09-07T16:00:00.000Z", "idempotencyKey": "{{idempotencyKey}}" }Structured result · checkpoint-accepted { "accepted": true, "seq": 4, "highWaterMark": 4, "suggestedNextPollAt": "2026-09-07T16:05:00.000Z", "coalesce": false, "controlBlock": { "state": { "sessionState": "running", "protocolVersion": "1.1" }, "allowedNextOperations": [ { "operation": "review_execution_skill_get", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_checkpoint_append", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_heartbeat", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_question_open", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_submit", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_release", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_sync", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_status", "preconditions": [ "Always callable as the documented fail-safe." ] } ], "completion": { "complete": false, "unmetRequirements": [], "certificateState": "not_applicable" }, "progress": { "checkpointHighWaterMark": 4, "openQuestionCount": 0, "leaseExpiresAt": "2026-09-07T16:15:00.000Z", "suggestedPollAt": "2026-09-07T16:05:00.000Z" }, "operatorAction": { "required": false } } }Result variant:
checkpoint-accepted. Read checkpoint4HighWaterMark from structuredContent.highWaterMark.Next: Prepare the schema-valid final result.
9. execution-checkpoint-submit
When the preceding step succeeds and this call is allowed by the current server state.
review_execution_checkpoint_append { "executionId": "{{executionId}}", "fenceGeneration": 1, "seq": 5, "activeSkillId": "engineering", "milestoneName": "submit", "safeSummary": "Final result is ready for submission.", "receipt": { "submissionRevision": 1 }, "clientObservedAt": "2026-09-07T16:00:00.000Z", "idempotencyKey": "{{idempotencyKey}}" }Structured result · checkpoint-accepted { "accepted": true, "seq": 5, "highWaterMark": 5, "suggestedNextPollAt": "2026-09-07T16:05:00.000Z", "coalesce": false, "controlBlock": { "state": { "sessionState": "running", "protocolVersion": "1.1" }, "allowedNextOperations": [ { "operation": "review_execution_skill_get", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_checkpoint_append", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_heartbeat", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_question_open", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_submit", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_release", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_sync", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_status", "preconditions": [ "Always callable as the documented fail-safe." ] } ], "completion": { "complete": false, "unmetRequirements": [], "certificateState": "not_applicable" }, "progress": { "checkpointHighWaterMark": 5, "openQuestionCount": 0, "leaseExpiresAt": "2026-09-07T16:15:00.000Z", "suggestedPollAt": "2026-09-07T16:05:00.000Z" }, "operatorAction": { "required": false } } }Result variant:
checkpoint-accepted. Read checkpoint5HighWaterMark from structuredContent.highWaterMark.Next: Sync once more, then submit only if the control block permits it.
10. execution-heartbeat
When the preceding step succeeds and this call is allowed by the current server state.
review_execution_heartbeat { "executionId": "{{executionId}}", "fenceGeneration": 1, "idempotencyKey": "{{idempotencyKey}}" }Structured result · lease-renewed { "leaseExpiresAt": "2026-09-07T16:15:00.000Z", "heartbeatRecommendedSeconds": 30, "controlBlock": { "state": { "sessionState": "running", "protocolVersion": "1.1" }, "allowedNextOperations": [ { "operation": "review_execution_skill_get", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_checkpoint_append", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_heartbeat", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_question_open", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_submit", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_release", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_sync", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_status", "preconditions": [ "Always callable as the documented fail-safe." ] } ], "completion": { "complete": false, "unmetRequirements": [], "certificateState": "not_applicable" }, "progress": { "checkpointHighWaterMark": 5, "openQuestionCount": 0, "leaseExpiresAt": "2026-09-07T16:15:00.000Z", "suggestedPollAt": "2026-09-07T16:05:00.000Z" }, "operatorAction": { "required": false } } }Result variant:
lease-renewed. Read leaseExpiresAt from structuredContent.leaseExpiresAt.Next: Schedule the next heartbeat from heartbeatRecommendedSeconds.
11. execution-sync
When the preceding step succeeds and this call is allowed by the current server state.
review_execution_sync { "executionId": "{{executionId}}", "cursor": "{{syncCursor}}", "fenceGeneration": 1 }Structured result · sync { "answers": [], "cancellationRequested": false, "serverCommands": [], "handoff": { "occurred": false, "currentFenceGeneration": 1 }, "lease": { "fenceGeneration": 1, "leaseExpiresAt": "2026-09-07T16:15:00.000Z", "current": true }, "nextCursor": "sync_fixture_after_checkpoint", "suggestedNextPollAt": "2026-09-07T16:05:00.000Z", "controlBlock": { "state": { "sessionState": "running", "protocolVersion": "1.1" }, "allowedNextOperations": [ { "operation": "review_execution_skill_get", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_checkpoint_append", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_heartbeat", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_question_open", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_submit", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_release", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_sync", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_status", "preconditions": [ "Always callable as the documented fail-safe." ] } ], "completion": { "complete": false, "unmetRequirements": [], "certificateState": "not_applicable" }, "progress": { "checkpointHighWaterMark": 5, "openQuestionCount": 0, "leaseExpiresAt": "2026-09-07T16:15:00.000Z", "suggestedPollAt": "2026-09-07T16:05:00.000Z" }, "operatorAction": { "required": false } } }Result variant:
sync. Read nextCursor from structuredContent.nextCursor.Next: Apply answers, cancellation, handoff, lease, and server commands before more work.
12. execution-status
When the preceding step succeeds and this call is allowed by the current server state.
review_execution_status { "executionId": "{{executionId}}" }Structured result · execution-status { "execution": { "executionId": "xex_fixture_engineering", "reviewSessionId": "rs_fixture_engineering", "state": "running", "currentFenceGeneration": 1, "activeSkillCursor": null }, "epoch": { "fenceGeneration": 1, "leaseExpiresAt": "2026-09-07T16:15:00.000Z", "heartbeatAt": "2026-09-07T16:00:30.000Z", "claimedByPrincipal": "example", "startedAt": "2026-09-07T16:00:00.000Z", "endedAt": null }, "checkpointHighWaterMark": 5, "openQuestionCount": 0, "certificateReference": null, "controlBlock": { "state": { "sessionState": "running", "protocolVersion": "1.1" }, "allowedNextOperations": [ { "operation": "review_execution_skill_get", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_checkpoint_append", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_heartbeat", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_question_open", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_submit", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_release", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_sync", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_status", "preconditions": [ "Always callable as the documented fail-safe." ] } ], "completion": { "complete": false, "unmetRequirements": [], "certificateState": "not_applicable" }, "progress": { "checkpointHighWaterMark": 5, "openQuestionCount": 0, "leaseExpiresAt": "2026-09-07T16:15:00.000Z", "suggestedPollAt": "2026-09-07T16:05:00.000Z" }, "operatorAction": { "required": false } } }Result variant:
execution-status. Read controlBlock from structuredContent.controlBlock.Next: Follow allowedNextOperations and the authoritative fence/lease/question counts.
13. execution-release
Alternative terminal branch only: invoke before submit when the human chooses relinquish/handoff; skip submit after release.
review_execution_release { "executionId": "{{executionId}}", "fenceGeneration": 1, "reason": "handoff", "idempotencyKey": "{{idempotencyKey}}" }Structured result · released { "released": true, "controlBlock": { "state": { "sessionState": "handed_off", "protocolVersion": "1.1" }, "allowedNextOperations": [ { "operation": "review_execution_claim", "preconditions": [ "Explicitly released for handoff — claimable by the next authorized harness." ] }, { "operation": "review_execution_status", "preconditions": [ "Always callable as the documented fail-safe." ] } ], "completion": { "complete": false, "unmetRequirements": [], "certificateState": "not_applicable" }, "progress": { "checkpointHighWaterMark": 5, "openQuestionCount": 0, "leaseExpiresAt": "2026-09-07T16:15:00.000Z", "suggestedPollAt": "2026-09-07T16:05:00.000Z" }, "operatorAction": { "required": false } } }Result variant:
released. Read released from structuredContent.released.Next: Stop; the next harness must claim a fresh epoch and repeat local evidence confirmation.
14. execution-submit
Completion branch only: invoke when controlBlock permits submit, no question is open, and release was not chosen.
review_execution_submit { "executionId": "{{executionId}}", "fenceGeneration": 1, "submissionRevision": 1, "canonicalBundleSha256": "{{canonicalBundleSha256}}", "result": { "reviewer": "engineering", "findings": [], "questions": [], "summaryOfChanges": "Validated retry-safe payment intent reuse." }, "idempotencyKey": "{{idempotencyKey}}" }Structured result · completed { "status": "completed", "outcome": "no_change", "briefVersionId": null, "briefVersionNum": null, "certificateReference": { "certificateId": "example", "state": "pending" }, "controlBlock": { "state": { "sessionState": "completed", "protocolVersion": "1.1" }, "allowedNextOperations": [ { "operation": "review_execution_status", "preconditions": [ "Always callable as the documented fail-safe." ] } ], "completion": { "complete": true, "unmetRequirements": [], "certificateState": "pending" }, "progress": { "checkpointHighWaterMark": 5, "openQuestionCount": 0, "leaseExpiresAt": "2026-09-07T16:15:00.000Z", "suggestedPollAt": "2026-09-07T16:05:00.000Z" }, "operatorAction": { "required": false } }, "cascade": { "status": "awaiting_local_claim", "runId": "run_fixture_review", "reviewSessionId": "rs_fixture_engineering", "cascadeStepId": "example", "controlBlock": { "state": { "sessionState": "awaiting_local_claim", "protocolVersion": "1.1" }, "allowedNextOperations": [ { "operation": "review_execution_grant_request", "preconditions": [ "A human must approve the execution grant before a harness can claim this run." ] }, { "operation": "review_execution_claim", "preconditions": [ "A human must approve the execution grant before a harness can claim this run." ] }, { "operation": "review_execution_status", "preconditions": [ "Always callable as the documented fail-safe." ] } ], "completion": { "complete": false, "unmetRequirements": [], "certificateState": "not_applicable" }, "progress": { "checkpointHighWaterMark": 0, "openQuestionCount": 0, "leaseExpiresAt": "2026-09-07T16:15:00.000Z", "suggestedPollAt": "2026-09-07T16:05:00.000Z" }, "operatorAction": { "required": false } } } }Result variant:
completed. Read cascade from structuredContent.cascade.Next: Follow cascade.status; request the next grant only for awaiting_local_claim and never wait for certificate signing.
Completion and recovery
Done when: The session is either explicitly released before submit or returns a completed submit response whose cascade instruction has been followed.
- Call review_execution_status whenever local context is lost.
- Replay identical mutations with the original key; changed payloads require new keys.
- Do not upload buffered receipts if another principal took over or the session was cancelled.
Errors
STALE_FENCE: The supplied fence generation is no longer current. Stop writes, call status/sync, and accept the authoritative handoff or recovery state.QUESTION_OPEN: Submit is blocked by a durable unanswered question. Sync and wait for a real attributed answer; never delete or fabricate the question.PROTOCOL_VERSION_UNSUPPORTED: No claimed protocol version is supported. Stop and update the harness integration before requesting a new claim.
Never assume
- The agent can approve or mint its own grant.
- Fence generations may be incremented locally.
- Release is required after terminal submit.
- Certificate signing must finish before exit.
- Upcoming skill bytes may be fetched early.
Open, answer, and supersede a durable question
Open a question only for a real build-shaping fork. A human supplies the accepted answer; the agent records that answer or an explicit superseding answer. Notification failure never erases the canonical inbox record.
Persist an owner decision before displaying it, accept only a real human answer, and recover correctly from conflict or operator supersession.
Requests you can make
- “Ask me which database migration strategy to use.”
- “Record my answer and resume the review.”
- “Correct my earlier answer to use an online migration.”
Prerequisites
Scopes: brief:read, review:execute
- Claimed execution is running or waiting_input
- Current fence is known
- Provide the answer; only a verified operator may supersede an accepted answer.
Ordered steps
1. question-checkpoint-wait-enter
When the preceding step succeeds and this call is allowed by the current server state.
review_execution_checkpoint_append { "executionId": "{{executionId}}", "fenceGeneration": 1, "seq": 6, "activeSkillId": "engineering", "milestoneName": "question_wait_enter", "safeSummary": "Preparing to wait for the owner on a durable migration question.", "receipt": { "clientQuestionId": "recipe-question-open-v1" }, "clientObservedAt": "2026-09-07T16:00:00.000Z", "idempotencyKey": "{{idempotencyKey}}" }Structured result · checkpoint-accepted { "accepted": true, "seq": 6, "highWaterMark": 6, "suggestedNextPollAt": "2026-09-07T16:05:00.000Z", "coalesce": false, "controlBlock": { "state": { "sessionState": "running", "protocolVersion": "1.1" }, "allowedNextOperations": [ { "operation": "review_execution_skill_get", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_checkpoint_append", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_heartbeat", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_question_open", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_submit", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_release", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_sync", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_status", "preconditions": [ "Always callable as the documented fail-safe." ] } ], "completion": { "complete": false, "unmetRequirements": [], "certificateState": "not_applicable" }, "progress": { "checkpointHighWaterMark": 6, "openQuestionCount": 0, "leaseExpiresAt": "2026-09-07T16:15:00.000Z", "suggestedPollAt": "2026-09-07T16:05:00.000Z" }, "operatorAction": { "required": false } } }Result variant:
checkpoint-accepted. Read checkpoint6HighWaterMark from structuredContent.highWaterMark.Next: Open the durable question before displaying it.
2. question-open
When the preceding step succeeds and this call is allowed by the current server state.
review_question_open { "executionId": "{{executionId}}", "fenceGeneration": 1, "clientQuestionId": "{{clientQuestionId}}", "text": "Which migration strategy should implementation use?", "reviewerRole": "engineering", "section": "technicalSolution", "options": [ "Online expand/contract", "Scheduled maintenance" ], "responseDeadlineHint": "2026-09-08T16:00:00.000Z", "idempotencyKey": "{{idempotencyKey}}" }Structured result · question-opened { "questionId": "q_fixture_database", "deduped": false, "responseDeadline": "2026-09-08T16:00:00.000Z", "deliveryState": [], "controlBlock": { "state": { "sessionState": "waiting_input", "protocolVersion": "1.1" }, "allowedNextOperations": [ { "operation": "review_execution_skill_get", "preconditions": [ "Consumes no hosted resource; a local answer resumes the epoch, or the polling harness may retain its bounded lease." ] }, { "operation": "review_question_answer", "preconditions": [ "Consumes no hosted resource; a local answer resumes the epoch, or the polling harness may retain its bounded lease." ] }, { "operation": "review_execution_sync", "preconditions": [ "Consumes no hosted resource; a local answer resumes the epoch, or the polling harness may retain its bounded lease." ] }, { "operation": "review_execution_heartbeat", "preconditions": [ "Consumes no hosted resource; a local answer resumes the epoch, or the polling harness may retain its bounded lease." ] }, { "operation": "review_execution_release", "preconditions": [ "Consumes no hosted resource; a local answer resumes the epoch, or the polling harness may retain its bounded lease." ] }, { "operation": "review_execution_status", "preconditions": [ "Always callable as the documented fail-safe." ] } ], "completion": { "complete": false, "unmetRequirements": [], "certificateState": "not_applicable" }, "progress": { "checkpointHighWaterMark": 6, "openQuestionCount": 1, "leaseExpiresAt": "2026-09-07T16:15:00.000Z", "suggestedPollAt": "2026-09-07T16:05:00.000Z" }, "operatorAction": { "required": false } } }Result variant:
question-opened. Read questionId from structuredContent.questionId.Next: Display the durable question and its options only after this call succeeds.
3. answer-question
Human action: The human chooses or writes the answer; preserve attribution and do not infer it.
Next: Submit exactly the answer the human provided.
4. question-answer
When the preceding step succeeds and this call is allowed by the current server state.
review_question_answer { "executionId": "{{executionId}}", "fenceGeneration": 1, "questionId": "{{questionId}}", "answerText": "Use online expand/contract.", "transmittingAgent": "codex", "humanAttribution": { "claimedName": "Repository owner" }, "idempotencyKey": "{{idempotencyKey}}" }Structured result · accepted-answer { "outcome": "accepted", "answerId": "example", "questionId": "q_fixture_database", "activeAnswer": { "answerId": "example", "channel": "local_harness", "answerText": "Use online expand/contract.", "answeredAt": "2026-09-07T16:03:00.000Z" }, "roundResumed": true, "controlBlock": { "state": { "sessionState": "running", "protocolVersion": "1.1" }, "allowedNextOperations": [ { "operation": "review_execution_skill_get", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_checkpoint_append", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_heartbeat", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_question_open", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_submit", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_release", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_sync", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_status", "preconditions": [ "Always callable as the documented fail-safe." ] } ], "completion": { "complete": false, "unmetRequirements": [], "certificateState": "not_applicable" }, "progress": { "checkpointHighWaterMark": 6, "openQuestionCount": 0, "leaseExpiresAt": "2026-09-07T16:15:00.000Z", "suggestedPollAt": "2026-09-07T16:05:00.000Z" }, "operatorAction": { "required": false } } }Result variant:
accepted-answer. Read activeAnswer from structuredContent.activeAnswer.Next: Resume dependent work only when this answer is accepted or matches the existing winner.
5. question-checkpoint-wait-exit
When the preceding step succeeds and this call is allowed by the current server state.
review_execution_checkpoint_append { "executionId": "{{executionId}}", "fenceGeneration": 1, "seq": 7, "activeSkillId": "engineering", "milestoneName": "question_wait_exit", "safeSummary": "The owner answer was accepted and dependent work may resume.", "receipt": { "questionId": "{{questionId}}", "answerAccepted": true }, "clientObservedAt": "2026-09-07T16:00:00.000Z", "idempotencyKey": "{{idempotencyKey}}" }Structured result · checkpoint-accepted { "accepted": true, "seq": 7, "highWaterMark": 7, "suggestedNextPollAt": "2026-09-07T16:05:00.000Z", "coalesce": false, "controlBlock": { "state": { "sessionState": "running", "protocolVersion": "1.1" }, "allowedNextOperations": [ { "operation": "review_execution_skill_get", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_checkpoint_append", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_heartbeat", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_question_open", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_submit", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_release", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_sync", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_status", "preconditions": [ "Always callable as the documented fail-safe." ] } ], "completion": { "complete": false, "unmetRequirements": [], "certificateState": "not_applicable" }, "progress": { "checkpointHighWaterMark": 7, "openQuestionCount": 0, "leaseExpiresAt": "2026-09-07T16:15:00.000Z", "suggestedPollAt": "2026-09-07T16:05:00.000Z" }, "operatorAction": { "required": false } } }Result variant:
checkpoint-accepted. Read checkpoint7HighWaterMark from structuredContent.highWaterMark.Next: Resume work from the accepted answer or follow an operator correction.
6. question-supersede
Only a verified human operator may invoke this correction path after an accepted answer.
review_question_answer_supersede { "executionId": "{{executionId}}", "questionId": "{{questionId}}", "correctedAnswerText": "Use an online expand/contract migration with a compatibility window.", "reason": "Owner clarified rollback requirements.", "idempotencyKey": "{{idempotencyKey}}" }Structured result · superseded { "outcome": "accepted", "newAnswerId": "ans_fixture_corrected", "supersededAnswerId": "ans_fixture_original", "recoveryCursor": { "invalidatedFromSeq": 1, "activeSkillCursor": null }, "controlBlock": { "state": { "sessionState": "running", "protocolVersion": "1.1" }, "allowedNextOperations": [ { "operation": "review_execution_skill_get", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_checkpoint_append", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_heartbeat", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_question_open", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_submit", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_release", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_sync", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_status", "preconditions": [ "Always callable as the documented fail-safe." ] } ], "completion": { "complete": false, "unmetRequirements": [], "certificateState": "not_applicable" }, "progress": { "checkpointHighWaterMark": 7, "openQuestionCount": 0, "leaseExpiresAt": "2026-09-07T16:15:00.000Z", "suggestedPollAt": "2026-09-07T16:05:00.000Z" }, "operatorAction": { "required": false } } }Result variant:
superseded. Read recoveryCursor from structuredContent.recoveryCursor.Next: Rework from recoveryCursor before final submission.
7. question-sync
When the preceding step succeeds and this call is allowed by the current server state.
review_execution_sync { "executionId": "{{executionId}}", "cursor": "{{syncCursor}}", "fenceGeneration": 1 }Structured result · sync { "answers": [], "cancellationRequested": false, "serverCommands": [], "handoff": { "occurred": false, "currentFenceGeneration": 1 }, "lease": { "fenceGeneration": 1, "leaseExpiresAt": "2026-09-07T16:15:00.000Z", "current": false }, "nextCursor": null, "suggestedNextPollAt": "2026-09-07T16:05:00.000Z", "controlBlock": { "state": { "sessionState": "running", "protocolVersion": "1.1" }, "allowedNextOperations": [ { "operation": "review_execution_skill_get", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_checkpoint_append", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_heartbeat", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_question_open", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_submit", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_release", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_sync", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_status", "preconditions": [ "Always callable as the documented fail-safe." ] } ], "completion": { "complete": false, "unmetRequirements": [], "certificateState": "not_applicable" }, "progress": { "checkpointHighWaterMark": 7, "openQuestionCount": 0, "leaseExpiresAt": "2026-09-07T16:15:00.000Z", "suggestedPollAt": "2026-09-07T16:05:00.000Z" }, "operatorAction": { "required": false } } }Result variant:
sync. Read answers from structuredContent.answers.Next: Apply the winning answer and any recovery cursor before continuing.
Completion and recovery
Done when: Every opened question has an accepted human answer and any supersession recovery work is complete.
- On answer conflict, use activeAnswer as the winner and ask the operator whether correction is needed.
- After supersede, discard dependent local conclusions from recoveryCursor onward.
Errors
QUESTION_OPEN: A terminal submit is attempted while a question remains unanswered. Wait, sync, and submit the actual human answer before retrying finalization.CONFLICTING_IDEMPOTENCY_REPLAY: The same mutation key is reused with changed answer text. Keep the old key only for identical replay; use a new key for the changed human answer.
Never assume
- The agent may answer its own owner question.
- Displaying a question locally makes it durable.
- A second ordinary answer silently replaces the winner.
Use bounded local evidence
List permitted sources, search within the project boundary, then fetch only the exact cited evidence. Keep raw repository dumps, secrets, and chain-of-thought out of checkpoints and submissions.
Inventory indexed sources, search selected opaque source ids, and redeem one opaque citation handle for bounded evidence.
Requests you can make
- “Find where retry idempotency is implemented.”
- “Show the evidence behind that repository citation.”
Prerequisites
Scopes: brief:read, review:execute
- Project id resolved
- Project context access granted
- Confirm any later local-worktree binding separately.
Ordered steps
1. context-sources-list
When the preceding step succeeds and this call is allowed by the current server state.
project_context_sources_list { "projectId": "{{projectId}}", "limit": 50 }Structured result · source-list { "sources": [ { "sourceId": "src_fixture_repository", "kind": "repository", "label": "throughlineos repository", "scope": { "kind": "project", "id": "prj_fixture_checkout" }, "status": "ready", "freshness": { "asOf": "2026-09-07T16:00:00.000Z", "coverage": "full" }, "provenance": "semel_indexed" } ], "nextCursor": null }Result variant:
source-list. Read sourceId from structuredContent.sources[0].sourceId.Next: Follow nextCursor to completion and distinguish ready, stale, degraded, and unavailable sources.
2. context-search
When the preceding step succeeds and this call is allowed by the current server state.
project_context_search { "projectId": "{{projectId}}", "sourceIds": [ "{{sourceId}}" ], "query": "payment retry idempotency", "limit": 20 }Structured result · search-results { "results": [ { "citation": { "citationHandle": "ctx1.repository.fixture", "sourceId": "src_fixture_repository", "provenance": "semel_indexed", "route": "exact", "score": 0.93, "kind": "repository", "repository": { "owner": "throughline", "name": "throughlineos" }, "revision": { "commitSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "revisionId": "rev_fixture_checkout" }, "path": "services/api/src/checkout.ts", "startLine": 42, "endLine": 58 } } ], "searchedSources": [ { "sourceId": "src_fixture_repository", "route": "exact", "resultCount": 1, "abstained": false } ] }Result variant:
search-results. Read citationHandle from structuredContent.results[0].citation.citationHandle.Next: Preserve the returned citationHandle exactly; inspect abstention metadata when no result exists.
3. context-evidence-get
When the preceding step succeeds and this call is allowed by the current server state.
project_context_evidence_get { "projectId": "{{projectId}}", "citationHandle": "{{citationHandle}}" }Structured result · bounded-evidence { "citation": { "citationHandle": "ctx1.repository.fixture", "sourceId": "src_fixture_repository", "provenance": "semel_indexed", "route": "exact", "score": 0, "kind": "repository", "repository": { "owner": "throughline", "name": "throughlineos" }, "revision": { "commitSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "revisionId": "rev_fixture_checkout" }, "path": "services/api/src/checkout.ts", "startLine": 42, "endLine": 58 }, "excerpt": "The checkout handler reuses the payment intent for a repeated idempotency key.", "truncated": false }Result variant:
bounded-evidence. Read excerpt from structuredContent.excerpt.Next: Cite the returned provenance/revision/path and disclose truncated when true.
Completion and recovery
Done when: The answer cites a server-resolved handle with provenance and truncation disclosed, or accurately reports no indexed match/abstention.
- Refresh source inventory after stale handles or index changes.
- Treat no match and an abstaining retrieval route as different outcomes.
Errors
CONTEXT_UNAVAILABLE: A selected source or citation cannot currently be resolved. Report its freshness/status and ask whether to wait or begin separately confirmed local evidence discovery.PROJECT_ACCESS_DENIED: The principal cannot reach the resolved project. Stop and have an operator correct the project allowlist; never select another project silently.
Never assume
- Repository citations may be fabricated.
- A no-result response proves absence when a source abstained.
- Opaque source ids or citation handles may be edited.
Connect an unattended agent
A workspace owner creates the scoped, show-once named token and places it in an environment or native secret reference. The agent proves read access without printing the value and cannot mint, widen, or rotate its own credential.
Have a human create and store a least-privilege named token, then prove it with a permitted read while preserving all human gates.
Requests you can make
- “Set up this agent to read Semel unattended.”
- “Verify the service token can list its allowed projects.”
Prerequisites
Scopes: brief:read
- Human can access Agent access settings
- Harness supports protected secret configuration
- Create the named token and place it in the harness secret store.
Ordered steps
1. create-named-token
Human action: Create a least-privilege named token in Agent access; never paste it into chat, docs URLs, or example files.
Next: Store it using the harness-supported secret or environment mechanism.
2. configure-named-token
Protocol action (configure_credential): Configure the token in protected harness storage.
Next: Reconnect and authenticate without printing the credential.
3. unattended-project-list
When the preceding step succeeds and this call is allowed by the current server state.
project_list {}Structured result · project-list { "projects": [] }Result variant:
project-list. Read projects from structuredContent.projects.Next: Confirm only expected projects are visible and retain human gates for mutations.
Completion and recovery
Done when: A live permitted read succeeds with the intended project visibility and the token never appears in generated content.
- Have the human rotate a leaked or unusable token in the portal.
- Re-run tools/list and the permitted read after credential replacement.
Errors
AUTHENTICATION_REQUIRED: The live MCP request has no valid bearer credential. Reauthenticate through the configured harness and retry the read or mutation.AUTHORIZATION_SCOPE_MISSING: The credential lacks a scope required by the selected operation. Stop and ask the human to issue a least-privilege grant containing the named scope.
Never assume
- A named token is delegated browser OAuth.
- Unattended execution bypasses explicit confirmation or human judgment gates.
- Secrets may be persisted in recipe/example files.
Revoke and rotate access
A human mints and installs a replacement credential, verifies it, and revokes the old grant or token. The agent can observe the resulting failure and resume after reauthorization; it cannot perform credential administration.
Keep credential administration human-owned, observe revocation as authentication failure, and restore access through protected harness configuration.
Requests you can make
- “Revoke this agent connection.”
- “Rotate the named token and reconnect the harness.”
Prerequisites
Scopes: none
- Existing agent credential or Connected apps entry
- Revoke or rotate in Connected apps or Agent access.
Ordered steps
1. revoke-in-portal
Human action: Revoke the Connected apps entry or rotate the named token in the Semel portal.
Next: Expect the old credential to fail authentication.
2. observe-revocation
Protocol action (authenticate): Attempt a fresh authenticated initialization with the old credential and classify its terminal auth failure.
Next: Do not retry a terminal revoked credential indefinitely.
3. supply-rotated-credential
Human action: Create the replacement credential and place it directly in protected harness configuration.
Next: Never send the credential through the conversation.
4. configure-rotated-credential
Protocol action (configure_credential): Replace the harness credential without writing it into docs or repository files.
Next: Reconnect, authenticate, and verify live capabilities.
5. verify-rotated-tools
Protocol action (tools_list): Read tools/list with the replacement credential.
Next: Confirm the required capability names and expected least-privilege scope.
Completion and recovery
Done when: The old credential is rejected and the human-controlled replacement authenticates with the expected capabilities.
- Distinguish a transient provider/network failure from terminal credential rejection before asking for rotation.
Errors
AUTHENTICATION_REQUIRED: The old credential is revoked or expired. Stop retrying it and wait for the human-managed replacement.
Never assume
- Credential revocation is an MCP admin tool.
- The agent may rotate or revoke its own authority.
- A transient outage requires deleting credentials.
Recover a stale or interrupted session
Read review_execution_status, then synchronize before any mutation. Never recreate the session. An expired lease or stale fence requires a new legal claim path; a sequence gap requires the exact next sequence; a terminal or cancelled run accepts no further mutation.
Discard stale local assumptions, recover the authoritative execution/epoch state, and follow only an allowed next operation.
Requests you can make
- “Resume this local review after the agent restarted.”
- “Recover the session after its lease expired.”
Prerequisites
Scopes: brief:read, review:execute
- A reviewSessionId or executionId is known
- Local execution state may be stale
- Approve a new recovery grant when the server requires one.
- Confirm local evidence again after cross-harness handoff.
Ordered steps
1. clear-stale-local-state
Protocol action (clear_stale_state): Mark cached fence, lease, question, and allowed-operation assumptions untrusted.
Next: Call status with one real accepted identifier variant.
2. stale-execution-status
When the preceding step succeeds and this call is allowed by the current server state.
review_execution_status { "reviewSessionId": "{{reviewSessionId}}" }Structured result · execution-status { "execution": { "executionId": "xex_fixture_engineering", "reviewSessionId": "rs_fixture_engineering", "state": "running", "currentFenceGeneration": 1, "activeSkillCursor": null }, "epoch": { "fenceGeneration": 1, "leaseExpiresAt": "2026-09-07T16:15:00.000Z", "heartbeatAt": "2026-09-07T16:00:30.000Z", "claimedByPrincipal": "example", "startedAt": "2026-09-07T16:00:00.000Z", "endedAt": null }, "checkpointHighWaterMark": 0, "openQuestionCount": 0, "certificateReference": null, "controlBlock": { "state": { "sessionState": "running", "protocolVersion": "1.1" }, "allowedNextOperations": [ { "operation": "review_execution_skill_get", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_checkpoint_append", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_heartbeat", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_question_open", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_submit", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_release", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_sync", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_status", "preconditions": [ "Always callable as the documented fail-safe." ] } ], "completion": { "complete": false, "unmetRequirements": [], "certificateState": "not_applicable" }, "progress": { "checkpointHighWaterMark": 0, "openQuestionCount": 0, "leaseExpiresAt": "2026-09-07T16:15:00.000Z", "suggestedPollAt": "2026-09-07T16:05:00.000Z" }, "operatorAction": { "required": false } } }Result variant:
execution-status. Read epoch from structuredContent.epoch; executionId from structuredContent.execution.executionId.Next: Inspect controlBlock, current epoch/lease, pending questions, and allowedNextOperations.
3. stale-execution-sync
When the preceding step succeeds and this call is allowed by the current server state.
review_execution_sync { "executionId": "{{executionId}}" }Structured result · sync { "answers": [], "cancellationRequested": false, "serverCommands": [], "handoff": { "occurred": false, "currentFenceGeneration": 1 }, "lease": { "fenceGeneration": 1, "leaseExpiresAt": "2026-09-07T16:15:00.000Z", "current": true }, "nextCursor": null, "suggestedNextPollAt": "2026-09-07T16:05:00.000Z", "controlBlock": { "state": { "sessionState": "running", "protocolVersion": "1.1" }, "allowedNextOperations": [ { "operation": "review_execution_skill_get", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_checkpoint_append", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_heartbeat", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_question_open", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_submit", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_release", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_sync", "preconditions": [ "The active epoch may progress, ask a question, submit, or release." ] }, { "operation": "review_execution_status", "preconditions": [ "Always callable as the documented fail-safe." ] } ], "completion": { "complete": false, "unmetRequirements": [], "certificateState": "not_applicable" }, "progress": { "checkpointHighWaterMark": 0, "openQuestionCount": 0, "leaseExpiresAt": "2026-09-07T16:15:00.000Z", "suggestedPollAt": "2026-09-07T16:05:00.000Z" }, "operatorAction": { "required": false } } }Result variant:
sync. Read handoff from structuredContent.handoff.Next: Accept cancellation/takeover, or follow the server-provided recovery/grant path.
Completion and recovery
Done when: The harness either resumes under the server-confirmed current epoch or stops with the exact operator/recovery action returned by controlBlock.
- Use reviewSessionId-only status when executionId was lost.
- Repeat local evidence confirmation after every cross-harness handoff.
Errors
LEASE_EXPIRED: The cached epoch no longer holds a live lease. Request the server-directed same-principal recovery path; never extend or reclaim it locally.CANCELLED: The server reports the session was cancelled. Stop and discard buffered writes; do not submit or reclaim.STALE_FENCE: Another epoch superseded the cached fence. Accept takeover/handoff and require a fresh authorized claim before any write.
Never assume
- Fence generations may be self-incremented.
- A stale session should create another review run.
- A cancelled or taken-over session may still accept buffered submit.
- A blind reclaim is safe.