← Files Codex SecurityARCHIVED FILE

scripts/workbench/handoff.py

11.1 KB · Nov 18, 2026 · 06:11 UTC

↓ Download file

See the change to this file →

"""Scan handoff state transitions for the Codex Security workbench."""

from __future__ import annotations

import argparse
import sqlite3
from typing import Any

from workbench_validation import optional_text, require_uuid

RECOVERY_HANDOFF_TOKEN_PREFIX = "recovery_"


def require_handoff_claim_token(value: str) -> str:
    """Normalize the claim UUID, retaining the prefix that marks a recovery handoff."""
    recovery_token = value.startswith(RECOVERY_HANDOFF_TOKEN_PREFIX)
    token = value.removeprefix(RECOVERY_HANDOFF_TOKEN_PREFIX) if recovery_token else value
    normalized = require_uuid(token, "claim-token")
    return f"{RECOVERY_HANDOFF_TOKEN_PREFIX}{normalized}" if recovery_token else normalized


def require_tokenless_scan_owner(
    connection: sqlite3.Connection,
    scan: sqlite3.Row,
    model_thread_id: str | None,
) -> None:
    """Check model callers against a recorded owner. Trusted local callers omit model_thread_id."""
    if model_thread_id is None or scan["handoff_claim_token"] is not None:
        return
    if scan["handoff_status"] == "pending":
        raise SystemExit(
            "This Codex Security scan handoff has not been delivered. "
            "Claim the pending Codex Security scan handoff before continuing."
        )
    owner = scan["continuation_thread_id"] or scan["deep_scan_owner_thread_id"]
    if owner is None:
        owner = connection.execute(
            "SELECT thread_id FROM workspaces WHERE id = ?", (scan["workspace_id"],)
        ).fetchone()[0]
    if owner is None:
        completed_import = scan["launch_kind"] == "import" and scan["status"] == "complete"
        if not completed_import:
            raise SystemExit("This scan is awaiting its owning Codex thread.")
    elif owner != model_thread_id:
        raise SystemExit("This scan requires its owning Codex thread.")


def require_current_continuation(
    scan: sqlite3.Row,
    claim_token: str | None,
    *,
    error_message: str,
) -> None:
    """Require the current claim token, allowing a tokenless continuation for legacy delivered scans."""
    if (
        scan["handoff_status"] == "delivered"
        and scan["handoff_claim_token"] is None
        and claim_token is None
    ):
        return
    if claim_token is None:
        raise SystemExit(error_message)
    if scan["handoff_claim_token"] != require_handoff_claim_token(claim_token):
        raise SystemExit(error_message)


def validate_handoff_delivery_thread(
    owning_thread_id: str | None,
    requesting_thread_id: str,
    claim_token: str,
) -> None:
    """Require the owning thread for delivery unless the caller presents a recovery claim token."""
    if owning_thread_id != requesting_thread_id and not claim_token.startswith(
        RECOVERY_HANDOFF_TOKEN_PREFIX
    ):
        raise SystemExit(
            "A scan handoff can only be marked delivered from its owning Codex thread."
        )


def claim_handoff_delivery(
    wb: Any,
    connection: sqlite3.Connection,
    args: argparse.Namespace,
) -> dict[str, Any]:
    """Claim a pending handoff and return the current workspace state.

    The first claim wins. When take_over_stale is requested, replacing an expired
    claim also clears the continuation and deep scan owner. Retrying the same claim
    or losing a competing claim returns the workspace state without changing ownership.
    """
    scan_id = require_uuid(args.scan_id, "scan-id")
    claim_token = require_handoff_claim_token(args.claim_token)
    timestamp = wb.now()
    with connection:
        scan = wb.require_scan(connection, scan_id)
        if scan["handoff_status"] != "pending" or scan["handoff_claim_token"] == claim_token:
            return wb.workspace_state(connection, scan["workspace_id"])
        updated = connection.execute(
            """
            UPDATE scans
            SET handoff_claimed_at = ?, handoff_claim_token = ?,
                continuation_thread_id = CASE
                    WHEN handoff_claim_token IS NULL THEN continuation_thread_id
                    ELSE NULL
                END,
                deep_scan_owner_thread_id = CASE
                    WHEN handoff_claim_token IS NULL THEN deep_scan_owner_thread_id
                    ELSE NULL
                END,
                updated_at = ?
            WHERE id = ? AND handoff_status = 'pending'
                AND (
                    handoff_claim_token IS NULL
                    OR (
                        ? = 1
                        AND (handoff_claimed_at IS NULL OR handoff_claimed_at <= ?)
                    )
                )
            """,
            (
                timestamp,
                claim_token,
                timestamp,
                scan["id"],
                int(args.take_over_stale),
                wb.stale_claim_before(),
            ),
        )
        if updated.rowcount != 1:
            return wb.workspace_state(connection, scan["workspace_id"])
    return wb.workspace_state(connection, scan["workspace_id"])


def release_handoff_delivery(
    wb: Any,
    connection: sqlite3.Connection,
    args: argparse.Namespace,
) -> dict[str, Any]:
    """Release a matching pending claim, detach its continuation, and return the workspace state."""
    scan_id = require_uuid(args.scan_id, "scan-id")
    claim_token = require_handoff_claim_token(args.claim_token)
    timestamp = wb.now()
    with connection:
        scan = wb.require_scan(connection, scan_id)
        connection.execute(
            """
            UPDATE scans
            SET handoff_claimed_at = NULL, handoff_claim_token = NULL,
                continuation_thread_id = NULL, deep_scan_owner_thread_id = NULL,
                updated_at = ?
            WHERE id = ? AND handoff_status = 'pending'
                AND handoff_claim_token = ?
            """,
            (timestamp, scan["id"], claim_token),
        )
    return wb.workspace_state(connection, scan["workspace_id"])


def attach_scan_continuation_thread(
    wb: Any,
    connection: sqlite3.Connection,
    args: argparse.Namespace,
) -> dict[str, Any]:
    """Bind the claimed scan to a continuation and return its workspace state.

    An immediate transaction serializes ownership changes. Reattaching the same
    thread is idempotent. A different thread or mismatched claim token raises SystemExit.
    """
    scan_id = require_uuid(args.scan_id, "scan-id")
    claim_token = require_handoff_claim_token(args.claim_token)
    thread_id = optional_text(args.thread_id, maximum=512)
    if thread_id is None:
        raise SystemExit("Codex Security continuation thread ID is required.")
    connection.execute("BEGIN IMMEDIATE")
    with connection:
        timestamp = wb.now()
        scan = wb.require_scan(connection, scan_id)
        if scan["handoff_claim_token"] != claim_token:
            raise SystemExit("Codex Security continuation thread claim token does not match.")
        if scan["continuation_thread_id"] is not None:
            if scan["continuation_thread_id"] != thread_id:
                raise SystemExit(
                    "Codex Security scan continuation is owned by another continuation."
                )
            connection.commit()
            return wb.workspace_state(connection, scan["workspace_id"])
        connection.execute(
            """
            UPDATE scans
            SET continuation_thread_id = ?,
                deep_scan_owner_thread_id = CASE
                    WHEN mode = 'deep' THEN ? ELSE deep_scan_owner_thread_id
                END,
                updated_at = ?
            WHERE id = ? AND continuation_thread_id IS NULL
                AND handoff_claim_token = ?
            """,
            (thread_id, thread_id, timestamp, scan["id"], claim_token),
        )
    return wb.workspace_state(connection, scan["workspace_id"])


def mark_handoff_delivered(
    wb: Any,
    connection: sqlite3.Connection,
    args: argparse.Namespace,
) -> dict[str, Any]:
    """Record delivery for the pending claim and return the workspace state.

    For standard scans this resets preflight progress. The same claim can confirm
    delivery again. A conflicting claim or invalid requesting thread raises SystemExit.
    """
    scan_id = require_uuid(args.scan_id, "scan-id")
    claim_token = require_handoff_claim_token(args.claim_token)
    thread_id = optional_text(args.thread_id, maximum=512)
    connection.execute("BEGIN IMMEDIATE")
    with connection:
        timestamp = wb.now()
        scan = wb.require_scan(connection, scan_id)
        if thread_id is not None:
            workspace = wb.require_workspace(connection, scan["workspace_id"])
            validate_handoff_delivery_thread(
                scan["continuation_thread_id"] or workspace["thread_id"],
                thread_id,
                claim_token,
            )
        if scan["handoff_status"] == "delivered":
            if scan["handoff_claim_token"] != claim_token:
                raise SystemExit(
                    "Codex Security handoff delivery is owned by another continuation."
                )
        else:
            updated = connection.execute(
                """
                UPDATE scans
                SET handoff_status = 'delivered', handoff_claimed_at = NULL,
                    updated_at = ?
                WHERE id = ? AND handoff_status = 'pending'
                    AND handoff_claim_token = ?
                """,
                (timestamp, scan["id"], claim_token),
            )
            if updated.rowcount != 1:
                raise SystemExit("Codex Security handoff delivery could not be recorded.")
            if scan["mode"] != "deep":
                connection.execute(
                    """
                    UPDATE scan_progress
                    SET phase_items_total = 0, phase_items_completed = 0,
                        phase_progress_unit = 'checks',
                        preflight_checks_total = 0, preflight_checks_completed = 0,
                        updated_at = ?
                    WHERE scan_id = ?
                    """,
                    (timestamp, scan["id"]),
                )
        began_review = (
            args.return_context
            and thread_id is not None
            and args.occurrence_id is None
            and scan["mode"] == "standard"
            and scan["status"] == "running"
            and scan["canceled_at"] is None
            and scan["phase"] == "preflight"
        )
        if began_review:
            connection.execute(
                "UPDATE scans SET phase = 'threat_model', updated_at = ? WHERE id = ?",
                (timestamp, scan_id),
            )
            connection.execute(
                """UPDATE scan_progress SET phase_items_total = 0, phase_items_completed = 0,
                   phase_progress_unit = NULL, updated_at = ? WHERE scan_id = ?""",
                (timestamp, scan_id),
            )
    if not args.return_context:
        return wb.workspace_state(connection, scan["workspace_id"])
    context = wb.get_scan(
        connection,
        argparse.Namespace(
            scan_id=scan_id,
            occurrence_id=args.occurrence_id,
            model_thread_id=thread_id or "",
            context_claim_token=claim_token,
        ),
    )
    if began_review:
        context["beganStandardReview"] = True
    return context

SHA-256: af4eb66124ea1d66b8625ab54c6e846a6d7375d242c5509fa0bf8ef75c202fe0