← Files Codex SecurityARCHIVED FILE

scripts/deep_scan_workbench.py

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

↓ Download file

See the change to this file →

"""Persist deterministic Codex Security Deep Scan orchestration state."""

from __future__ import annotations

import argparse
import json
import os
import sqlite3
import sys
import uuid
from datetime import datetime, timedelta
from pathlib import Path
from typing import Any

sys.path.insert(0, str(Path(__file__).resolve().parent))
import workbench_saved_results as saved_results
from deep_scan_config import resolve_deep_scan_setup
from workbench.handoff import require_current_continuation, require_tokenless_scan_owner
from workbench.storage import (
    archived_deep_path,
    create_private_directory,
    saved_deep_workers,
    worker_usage_directory,
)
from workbench_constants import PHASES
from workbench_source_scopes import capture_source_scopes
from workbench_target import directory_snapshot_regular_file_count
from workbench_target_state import require_scan_checkout_owner
from workbench_validation import optional_text, require_uuid, user_context_argument

DEEP_SCAN_COORDINATOR_LEASE_SECONDS = 30
DEEP_SCAN_LEGACY_COORDINATOR_GRACE_SECONDS = 120
DEEP_SCAN_PUBLICATION_ERROR_SEPARATOR = "\nOriginal Deep Scan failure:\n"


_dependencies: Any = None


def configure(dependencies: Any) -> None:
    global _dependencies
    _dependencies = dependencies


def dependencies() -> Any:
    if _dependencies is None:
        raise RuntimeError("Deep Scan workbench dependencies are not configured.")
    return _dependencies


def deep_scan_error(run: sqlite3.Row) -> str | None:
    """Return recorded error messages, publication error first, or None if both are absent."""
    original = run["error_message"]
    publication = run["publication_error_message"]
    if not isinstance(publication, str):
        return original if isinstance(original, str) else None
    if not isinstance(original, str):
        return publication
    return publication + DEEP_SCAN_PUBLICATION_ERROR_SEPARATOR + original


def _parse_timestamp(value: str) -> datetime:
    if isinstance(value, str) and value.endswith(("Z", "z")):
        value = value[:-1] + "+00:00"
    return datetime.fromisoformat(value)


def require_deep_scan_run(connection: sqlite3.Connection, scan_id: str) -> sqlite3.Row:
    scan_id = require_uuid(scan_id, "scan-id")
    row = connection.execute(
        "SELECT * FROM deep_scan_runs WHERE scan_id = ?", (scan_id,)
    ).fetchone()
    if row is None:
        raise SystemExit("Codex Security Deep Scan orchestration state not found.")
    return row


def deep_scan_deadline_reached(run: sqlite3.Row) -> bool:
    """Return whether the time since run creation has reached its configured limit in hours."""
    elapsed = _parse_timestamp(dependencies().now()) - _parse_timestamp(str(run["created_at"]))
    return elapsed.total_seconds() / 3600 >= run["max_time_hours"]


def require_deep_scan_ready_for_parent_completion(
    connection: sqlite3.Connection, scan: sqlite3.Row
) -> None:
    """Require a succeeded discovery run with a saved manifest before a Deep Scan completes.

    For a capped run, also verify its workers have finished. Raise SystemExit
    when a completion requirement fails. Other scan modes can complete directly.
    """
    if scan["mode"] != "deep":
        return
    run = connection.execute(
        "SELECT status, manifest_path, terminal_reason FROM deep_scan_runs WHERE scan_id = ?",
        (scan["id"],),
    ).fetchone()
    if run is None or run["status"] != "succeeded" or run["manifest_path"] is None:
        raise SystemExit(
            "Deep Scan discovery orchestration must finish and persist its manifest before "
            "the parent scan can be completed."
        )
    if run["terminal_reason"] == "capped":
        require_deep_scan_workers_finished(connection, scan["id"], "capped")


def require_deep_scan_workers_finished(
    connection: sqlite3.Connection,
    scan_id: str,
    terminal_reason: str,
    *,
    has_omitted_workers: bool = False,
) -> None:
    """Check execution state for coordinator completion and resumed parent publication."""
    failed_worker = connection.execute(
        """
        SELECT 1 FROM deep_scan_workers AS failed
        WHERE failed.scan_id = ? AND failed.status = 'failed'
            AND (? != 'saturated' OR failed.kind != 'discovery')
            AND (
                failed.kind != 'dedup'
                OR NOT EXISTS (
                    SELECT 1 FROM deep_scan_dedup_inputs AS failed_inputs
                    WHERE failed_inputs.dedup_worker_id = failed.id
                )
                OR EXISTS (
                    SELECT 1 FROM deep_scan_dedup_inputs AS failed_inputs
                    WHERE failed_inputs.dedup_worker_id = failed.id
                        AND NOT EXISTS (
                            SELECT 1
                            FROM deep_scan_dedup_inputs AS replacement_inputs
                            JOIN deep_scan_workers AS replacement
                                ON replacement.scan_id = replacement_inputs.scan_id
                                AND replacement.id = replacement_inputs.dedup_worker_id
                            WHERE replacement_inputs.scan_id = failed.scan_id
                                AND replacement_inputs.discovery_worker_id =
                                    failed_inputs.discovery_worker_id
                                AND replacement.kind = 'dedup'
                                AND replacement.status = 'succeeded'
                        )
                )
            )
        LIMIT 1
        """,
        (scan_id, terminal_reason),
    ).fetchone()
    if failed_worker is not None:
        raise SystemExit("Deep Scan cannot finish after a worker has failed.")
    active_worker = connection.execute(
        """
        SELECT 1 FROM deep_scan_workers
        WHERE scan_id = ? AND status IN ('queued', 'running')
        LIMIT 1
        """,
        (scan_id,),
    ).fetchone()
    if active_worker is not None:
        raise SystemExit("Deep Scan cannot finish while workers are active.")
    merging_worker = connection.execute(
        """
        SELECT 1 FROM deep_scan_workers
        WHERE scan_id = ? AND merge_state = 'merging'
        LIMIT 1
        """,
        (scan_id,),
    ).fetchone()
    if merging_worker is not None:
        raise SystemExit("Deep Scan cannot finish while discovery output is merging.")
    if terminal_reason == "capped" and has_omitted_workers:
        raise SystemExit("Deep Scan capped completion cannot declare omitted buffered workers.")
    if (
        terminal_reason == "capped"
        and connection.execute(
            "SELECT 1 FROM deep_scan_workers WHERE scan_id = ? "
            "AND kind = 'discovery' AND merge_state = 'buffered' LIMIT 1",
            (scan_id,),
        ).fetchone()
        is not None
    ):
        raise SystemExit("Deep Scan cannot finish capped while discovery output remains buffered.")


def require_owned_scan(
    connection: sqlite3.Connection, scan_id: str, thread_id: str
) -> tuple[sqlite3.Row, sqlite3.Row]:
    """Return the scan and workspace rows or raise SystemExit unless thread_id matches the recorded owner."""
    scan = dependencies().require_scan(connection, scan_id)
    workspace = dependencies().require_workspace(connection, scan["workspace_id"])
    owner = optional_text(thread_id, maximum=512)
    if owner is None:
        raise SystemExit("thread-id is required.")
    persisted_owner = scan["deep_scan_owner_thread_id"] or workspace["thread_id"]
    if persisted_owner != owner:
        raise SystemExit("A scan can only be orchestrated from its owning Codex thread.")
    return scan, workspace


def deep_scan_path(
    scan: sqlite3.Row,
    value: str,
    label: str,
    *,
    kind: str,
) -> str:
    """Return the canonical absolute path to an existing scan-local file or directory of the requested kind."""
    supplied = Path(value).expanduser()
    if not supplied.is_absolute():
        raise SystemExit(f"{label} must be an absolute path inside the scan directory.")
    try:
        resolved = supplied.resolve(strict=True)
        scan_dir = dependencies().require_canonical_scan_directory(Path(scan["scan_dir"]))
        resolved.relative_to(scan_dir)
    except (OSError, RuntimeError, ValueError) as exc:
        raise SystemExit(f"{label} must be an existing path inside the scan directory.") from exc
    if os.path.normcase(resolved) != os.path.normcase(supplied.absolute()):
        raise SystemExit(f"{label} must be a canonical non-symlink path.")
    if kind == "file" and not resolved.is_file():
        raise SystemExit(f"{label} must be a regular file.")
    if kind == "directory" and not resolved.is_dir():
        raise SystemExit(f"{label} must be a directory.")
    return str(resolved)


def deep_scan_output_path(scan: sqlite3.Row, value: str, label: str) -> str:
    """Validate an absolute output path under the scan directory, allowing a new file under an existing parent."""
    supplied = Path(value).expanduser()
    if not supplied.is_absolute():
        raise SystemExit(f"{label} must be an absolute path inside the scan directory.")
    if supplied.exists():
        return deep_scan_path(scan, str(supplied), label, kind="file")
    parent = Path(deep_scan_path(scan, str(supplied.parent), label, kind="directory"))
    output = parent / supplied.name
    if os.path.normcase(output) != os.path.normcase(supplied.absolute()):
        raise SystemExit(f"{label} must be a canonical non-symlink path.")
    return str(output)


def promote_staged_file(staged_path: str, output_path: str) -> tuple[Path, Path, Path | None]:
    """Publish the staged file and return the paths needed to finalize or undo the move."""
    staged = Path(staged_path)
    output = Path(output_path)
    if staged == output:
        raise SystemExit("A staged Deep Scan artifact must not be its published output path.")
    backup = output.with_name(f".{output.name}.{uuid.uuid4()}.backup") if output.exists() else None
    if backup is not None:
        os.replace(output, backup)
    try:
        os.replace(staged, output)
    except BaseException:
        if backup is not None:
            os.replace(backup, output)
        raise
    return staged, output, backup


def rollback_staged_file(promotion: tuple[Path, Path, Path | None]) -> None:
    """Move the published file back to staging and restore the previous output if present."""
    staged, output, backup = promotion
    if output.exists():
        os.replace(output, staged)
    if backup is not None:
        os.replace(backup, output)


def finish_staged_file(promotion: tuple[Path, Path, Path | None]) -> None:
    """Remove the previous output saved during promotion."""
    backup = promotion[2]
    if backup is not None:
        backup.unlink(missing_ok=True)


def publication_matches_snapshot(publication: Path, snapshot: Path) -> bool:
    """Return whether the publication and snapshot identify the same file or contain identical bytes."""
    try:
        if publication.samefile(snapshot):
            return True
        if publication.stat().st_size != snapshot.stat().st_size:
            return False
        with publication.open("rb") as published, snapshot.open("rb") as source:
            while True:
                published_chunk = published.read(1024 * 1024)
                source_chunk = source.read(1024 * 1024)
                if published_chunk != source_chunk:
                    return False
                if not published_chunk:
                    return True
    except OSError:
        return False


def canonical_discovery_artifacts(scan: sqlite3.Row) -> dict[str, str]:
    discovery_dir = Path(scan["scan_dir"]) / "artifacts" / "02_discovery"
    return {
        name: deep_scan_path(scan, str(discovery_dir / filename), label, kind="file")
        for name, filename, label in (
            ("inScopeFilesPath", "in_scope_files.txt", "Canonical in-scope inventory path"),
            ("candidateLedgerPath", "candidate_ledger.jsonl", "Canonical candidate ledger path"),
        )
    }


def deep_scan_state(connection: sqlite3.Connection, scan_id: str) -> dict[str, Any]:
    """Return persisted orchestration state including settings, workers, artifacts, and deduplication inputs.

    Order workers by creation time and ID. Retain the recorded order of each
    deduplication worker’s discovery inputs.
    """
    run = require_deep_scan_run(connection, scan_id)
    scan = dependencies().require_scan(connection, run["scan_id"])
    worker_rows = saved_deep_workers(connection, scan)
    input_rows = connection.execute(
        """
        SELECT dedup_worker_id, discovery_worker_id, input_order
        FROM deep_scan_dedup_inputs
        WHERE scan_id = ?
        ORDER BY dedup_worker_id, input_order
        """,
        (run["scan_id"],),
    )
    manifest_path = archived_deep_path(Path(scan["scan_dir"]), run["manifest_path"])
    canonical_artifacts = None
    if (
        run["canonical_inventory_path"] is None
        and run["status"] == "succeeded"
        and manifest_path is not None
        and manifest_path != str(Path(scan["scan_dir"]) / "scan-manifest.json")
        and (Path(scan["scan_dir"]) / "artifacts" / "02_discovery" / "in_scope_files.txt").exists()
    ):
        canonical_artifacts = canonical_discovery_artifacts(scan)
        if (
            run["terminal_reason"] == "capped"
            and run["completion_sequence"] == 0
            and deep_scan_deadline_reached(run)
            and Path(canonical_artifacts["candidateLedgerPath"]).stat().st_size != 0
        ):
            raise SystemExit(
                "A capped Deep Scan without completed discoveries requires an empty "
                "candidate ledger."
            )
    recipe = json.loads(scan["recipe_json"]) if scan["recipe_json"] is not None else {}
    return {
        "scanId": run["scan_id"],
        "sdkOwnsCompletion": scan["recipe_json"] is not None,
        "serviceTier": run["service_tier"],
        **({"severityRubric": recipe["severityRubric"]} if "severityRubric" in recipe else {}),
        "targetPath": scan["target_path"],
        "scope": scan["scope"],
        "includePaths": dependencies().requested_scan_paths(scan),
        "filePaths": dependencies().requested_scan_file_paths(scan),
        "userContext": (
            json.loads(run["discovery_user_context_json"])
            if run["discovery_user_context_json"] is not None
            else scan["user_context"]
        ),
        "scanDir": scan["scan_dir"],
        "workerUsageDirectory": str(worker_usage_directory(run["scan_id"])),
        "schemaVersion": run["schema_version"],
        "workflowVersion": run["workflow_version"],
        "coordinatorGeneration": run["coordinator_generation"],
        "status": run["status"],
        "phase": run["phase"],
        # Older coordinators could persist discovery on the parent before dispatching.
        "discoveryStarted": (
            PHASES.index(scan["phase"]) >= PHASES.index("discovery")
            or run["phase"] in {"discovery", "reducing"}
        ),
        "config": {
            "workers": run["workers"],
            "subagents": run["subagents"],
            "stopAfterNoNew": run["stop_after_no_new"],
            "stopAfterConsecutiveErrors": run["stop_after_consecutive_errors"],
            "maxDiscoveryRuns": run["max_discovery_runs"],
            "maxTimeHours": run["max_time_hours"],
        },
        "dispatchedCount": run["discovery_runs_dispatched"],
        "completionSequence": run["completion_sequence"],
        "noNewStreak": run["consecutive_no_new"],
        "consecutiveErrors": run["consecutive_errors"],
        "cancelRequested": bool(run["cancel_requested"]),
        "canonicalArtifacts": canonical_artifacts,
        "manifestPath": manifest_path,
        "terminalReason": run["terminal_reason"],
        "error": deep_scan_error(run),
        "createdAt": run["created_at"],
        "updatedAt": run["updated_at"],
        "completedAt": run["completed_at"],
        "workers": [deep_scan_worker_state(row) for row in worker_rows],
        "dedupInputs": [
            {
                "dedupWorkerId": row["dedup_worker_id"],
                "discoveryWorkerId": row["discovery_worker_id"],
                "inputOrder": row["input_order"],
            }
            for row in input_rows
        ],
    }


def independent_review_progress(
    connection: sqlite3.Connection, scan_id: str, *, parent_running: bool
) -> dict[str, int | str] | None:
    """Return completed and allowed review counts and the consolidation state, or None for a missing run."""
    run = connection.execute(
        """
        SELECT completion_sequence, phase, updated_at, max_discovery_runs
        FROM deep_scan_runs
        WHERE scan_id = ?
        """,
        (scan_id,),
    ).fetchone()
    if run is None:
        return None
    active, buffered = connection.execute(
        """
        SELECT COUNT(*) FILTER (WHERE status IN ('queued', 'running')),
               COUNT(*) FILTER (WHERE status = 'succeeded' AND merge_state = 'buffered')
        FROM deep_scan_workers
        WHERE scan_id = ? AND kind = 'discovery'
        """,
        (scan_id,),
    ).fetchone()
    consolidating = run["phase"] in {"reducing", "terminal"} or (active == 0 and buffered > 0)
    return {
        "active": int(active),
        "completed": int(run["completion_sequence"]),
        "maximum": int(run["max_discovery_runs"]),
        "consolidating": parent_running and consolidating,
        "updatedAt": str(run["updated_at"]),
    }


def deep_scan_worker_state(row: sqlite3.Row) -> dict[str, Any]:
    return {
        "id": row["id"],
        "kind": row["kind"],
        "status": row["status"],
        "mergeState": row["merge_state"],
        "promptPath": row["prompt_path"],
        "artifactDir": row["artifact_dir"],
        "resultManifestPath": row["result_manifest_path"],
        "attempt": row["attempt"],
        "sdkThreadId": row["sdk_thread_id"],
        "completionSequence": row["completion_sequence"],
        "error": row["error_message"],
        "createdAt": row["created_at"],
        "startedAt": row["started_at"],
        "completedAt": row["completed_at"],
        "updatedAt": row["updated_at"],
    }


def deep_scan_result(
    connection: sqlite3.Connection,
    scan_id: str,
    *,
    start_disposition: str | None = None,
) -> dict[str, Any]:
    result: dict[str, Any] = {"deepScan": deep_scan_state(connection, scan_id)}
    if start_disposition is not None:
        result["startDisposition"] = start_disposition
    return result


def effective_deep_scan_config(
    args: argparse.Namespace, workspace: sqlite3.Row | None = None
) -> dict[str, Any]:
    """Use persisted workspace settings when available, otherwise resolve the current launch configuration."""
    if workspace is not None and workspace["deep_scan_config_json"] is not None:
        return json.loads(workspace["deep_scan_config_json"])
    return resolve_deep_scan_setup(project_json=args.deep_scan_project_json)


def ensure_deep_scan_run(
    connection: sqlite3.Connection,
    scan: sqlite3.Row,
    config: dict[str, int | float],
    workflow_version: str,
    timestamp: str,
    *,
    service_tier: str | None,
    pending_target_project_path: str | None = None,
) -> sqlite3.Row:
    """Return the existing orchestration row or initialize one for a running Deep Scan with the supplied settings."""
    existing = connection.execute(
        "SELECT * FROM deep_scan_runs WHERE scan_id = ?", (scan["id"],)
    ).fetchone()
    if existing is not None:
        return existing
    if scan["mode"] != "deep":
        raise SystemExit("Deep Scan orchestration requires a scan in deep mode.")
    if scan["status"] != "running":
        raise SystemExit("Only a running Deep Scan can start orchestration.")
    connection.execute(
        """
        INSERT INTO deep_scan_runs (
            scan_id, schema_version, workflow_version, status, phase,
            workers, subagents, stop_after_no_new, stop_after_consecutive_errors,
            max_discovery_runs, max_time_hours, discovery_user_context_json,
            created_at, updated_at, service_tier, pending_target_project_path
        ) VALUES (?, 1, ?, 'running', 'setup', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
        """,
        (
            scan["id"],
            workflow_version,
            config["workers"],
            config["subagents"],
            config["stopAfterNoNew"],
            config["stopAfterConsecutiveErrors"],
            config["maxDiscoveryRuns"],
            config["maxTimeHours"],
            json.dumps(scan["user_context"]),
            timestamp,
            timestamp,
            service_tier,
            pending_target_project_path,
        ),
    )
    return require_deep_scan_run(connection, scan["id"])


def existing_deep_scan_for_target(
    connection: sqlite3.Connection, thread_id: str, target_path: str, scope: str
) -> sqlite3.Row | None:
    return connection.execute(
        """
        SELECT scans.*
        FROM scans
        JOIN workspaces ON workspaces.id = scans.workspace_id
        WHERE (workspaces.thread_id = ? OR workspaces.thread_id IS NULL)
            AND COALESCE(scans.deep_scan_owner_thread_id, workspaces.thread_id) = ?
            AND scans.target_path = ?
            AND scans.scope = ?
            AND scans.mode = 'deep'
            AND scans.status = 'running'
        ORDER BY scans.updated_at DESC, scans.started_at DESC, scans.id
        LIMIT 1
        """,
        (thread_id, thread_id, target_path, scope),
    ).fetchone()


def terminal_deep_scan_for_target_snapshot(
    connection: sqlite3.Connection,
    thread_id: str,
    target_path: str,
    scope: str,
    user_context: str | None,
    project_path: str,
    revision: str,
    snapshot_digest: str,
    target_device: int | str,
    target_inode: int | str,
) -> sqlite3.Row | None:
    """Recover a matching terminal headless result, including after the parent was sealed."""
    return connection.execute(
        """
        SELECT scans.*
        FROM scans
        JOIN deep_scan_runs ON deep_scan_runs.scan_id = scans.id
        JOIN workspaces ON workspaces.id = scans.workspace_id
        WHERE scans.target_path = ?
            AND scans.scope = ?
            AND deep_scan_runs.discovery_user_context_json = ?
            AND scans.mode = 'deep'
            AND (
                (scans.status = 'running'
                    AND COALESCE(scans.deep_scan_owner_thread_id, workspaces.thread_id) <> ?)
                OR (scans.status = 'complete'
                    AND deep_scan_runs.pending_target_project_path IS NOT NULL)
            )
            AND (deep_scan_runs.pending_target_project_path IS NULL
                OR deep_scan_runs.pending_target_project_path = ?)
            AND scans.canceled_at IS NULL
            AND scans.recipe_json IS NULL
            AND scans.target_revision = ?
            AND scans.target_snapshot_digest = ?
            AND scans.target_device = ?
            AND scans.target_inode = ?
            AND scans.handoff_status = 'delivered'
            AND scans.handoff_claim_token IS NULL
            AND scans.continuation_thread_id IS NULL
            AND workspaces.active_scan_id = scans.id
            AND deep_scan_runs.status = 'succeeded'
            AND deep_scan_runs.phase = 'terminal'
            AND deep_scan_runs.cancel_requested = 0
            AND deep_scan_runs.terminal_reason IN ('saturated', 'capped')
            AND deep_scan_runs.manifest_path IS NOT NULL
            AND deep_scan_runs.completed_at IS NOT NULL
        ORDER BY (COALESCE(scans.deep_scan_owner_thread_id, workspaces.thread_id) = ?) DESC,
            deep_scan_runs.completed_at DESC, scans.updated_at DESC, scans.id
        LIMIT 1
        """,
        (
            target_path,
            scope,
            json.dumps(user_context),
            thread_id,
            project_path,
            revision,
            snapshot_digest,
            target_device,
            target_inode,
            thread_id,
        ),
    ).fetchone()


def begin_deep_scan_for_scan(
    connection: sqlite3.Connection,
    scan_id: str,
    thread_id: str,
    args: argparse.Namespace,
) -> dict[str, Any]:
    scan_id = require_uuid(scan_id, "scan-id")
    candidate = dependencies().require_scan(connection, scan_id)
    require_scan_checkout_owner(connection, candidate)
    model_thread_id = getattr(args, "model_thread_id", None)
    require_tokenless_scan_owner(connection, candidate, model_thread_id)
    workspace = dependencies().require_workspace(connection, candidate["workspace_id"])
    if (
        candidate["mode"] == "deep"
        and candidate["status"] == "running"
        and (
            candidate["recipe_json"] is not None or candidate["continuation_thread_id"] == thread_id
        )
        and candidate["handoff_status"] == "delivered"
        and candidate["deep_scan_owner_thread_id"] is None
        and workspace["thread_id"] is None
    ):
        require_current_continuation(
            candidate,
            args.claim_token,
            error_message="Deep Scan orchestration is owned by another continuation.",
        )
        timestamp = dependencies().now()
        with connection:
            # Legacy scans can share a workspace. Only registered scans claim the workspace.
            if candidate["recipe_json"] is not None:
                claimed_workspace = connection.execute(
                    "UPDATE workspaces SET thread_id = ?, updated_at = ? "
                    "WHERE id = ? AND thread_id IS NULL",
                    (thread_id, timestamp, workspace["id"]),
                )
                if claimed_workspace.rowcount != 1:
                    raise SystemExit(
                        "A scan can only be orchestrated from its owning Codex thread."
                    )
            claimed_scan = connection.execute(
                "UPDATE scans SET deep_scan_owner_thread_id = ?, updated_at = ? "
                "WHERE id = ? AND deep_scan_owner_thread_id IS NULL "
                "AND handoff_status = 'delivered' AND handoff_claim_token IS ? "
                "AND (continuation_thread_id = ? OR (recipe_json IS NOT NULL AND "
                "(handoff_claim_token IS NOT NULL OR (? IS NULL AND continuation_thread_id IS NULL))))",
                (
                    thread_id,
                    timestamp,
                    scan_id,
                    candidate["handoff_claim_token"],
                    thread_id,
                    model_thread_id,
                ),
            )
            if claimed_scan.rowcount != 1:
                raise SystemExit("A scan can only be orchestrated from its owning Codex thread.")
    scan, _ = require_owned_scan(connection, scan_id, thread_id)
    require_current_continuation(
        scan,
        args.claim_token,
        error_message="Deep Scan orchestration is owned by another continuation.",
    )
    if scan["mode"] != "deep":
        raise SystemExit("Deep Scan orchestration requires a scan in deep mode.")
    existing = connection.execute(
        "SELECT scan_id FROM deep_scan_runs WHERE scan_id = ?", (scan_id,)
    ).fetchone()
    if args.join_only and existing is None and workspace["deep_scan_config_json"] is None:
        return {"newScanTarget": scan["target_path"]}
    model = optional_text(args.model, maximum=200)
    reasoning_effort = optional_text(args.reasoning_effort, maximum=32)
    if model is not None or reasoning_effort is not None:
        connection.execute(
            """
            UPDATE scans
            SET model = COALESCE(?, model), reasoning_effort = COALESCE(?, reasoning_effort)
            WHERE id = ?
            """,
            (model, reasoning_effort, scan_id),
        )
        connection.commit()
    if existing is not None:
        return deep_scan_result(connection, scan_id, start_disposition="joined")
    workspace = dependencies().require_workspace(connection, scan["workspace_id"])
    configuration = effective_deep_scan_config(args, workspace)
    config = configuration["settings"]
    workflow_version = optional_text(args.workflow_version, maximum=256)
    if workflow_version is None:
        raise SystemExit("workflow-version is required.")
    connection.execute("BEGIN IMMEDIATE")
    with connection:
        scan, _ = require_owned_scan(connection, scan_id, thread_id)
        require_scan_checkout_owner(connection, scan)
        require_current_continuation(
            scan,
            args.claim_token,
            error_message="Deep Scan orchestration is owned by another continuation.",
        )
        connection.execute(
            "UPDATE workspaces SET deep_scan_config_json = ? WHERE id = ? AND deep_scan_config_json IS NULL",
            (json.dumps(configuration), workspace["id"]),
        )
        ensure_deep_scan_run(
            connection,
            scan,
            config,
            workflow_version,
            dependencies().now(),
            service_tier=args.service_tier,
        )
    return deep_scan_result(connection, scan_id, start_disposition="created")


def begin_deep_scan_for_target(
    connection: sqlite3.Connection, args: argparse.Namespace, thread_id: str
) -> dict[str, Any]:
    target = dependencies().require_target(args.target_path)
    dependencies().require_scannable_target(target)
    scope = dependencies().require_scope(args.scope, "deep", target)
    target_path = str(target)
    existing = existing_deep_scan_for_target(connection, thread_id, target_path, scope)
    if existing is not None:
        return begin_deep_scan_for_scan(connection, existing["id"], thread_id, args)
    user_context = user_context_argument(args)
    # Keep the requested spelling so a continuation can match a removed file or symlink.
    # NULL means no result is pending. The empty string denotes a launch with no project file.
    project_path = args.project_config_path or ""
    # Avoid hashing the checkout during this probe when a fresh scan needs its configuration.
    if (
        args.join_only
        and not connection.execute(
            """
            SELECT 1 FROM scans JOIN deep_scan_runs ON deep_scan_runs.scan_id = scans.id
            WHERE scans.target_path = ? AND scans.scope = ?
                AND (scans.status = 'running'
                    OR (scans.status = 'complete'
                        AND deep_scan_runs.pending_target_project_path IS NOT NULL))
                AND (deep_scan_runs.pending_target_project_path IS NULL
                    OR deep_scan_runs.pending_target_project_path = ?)
                AND scans.recipe_json IS NULL
                AND scans.handoff_claim_token IS NULL AND scans.continuation_thread_id IS NULL
                AND deep_scan_runs.status = 'succeeded'
                AND deep_scan_runs.discovery_user_context_json = ?
            LIMIT 1
            """,
            (target_path, scope, project_path, json.dumps(user_context)),
        ).fetchone()
    ):
        return {"newScanTarget": target_path}
    target_metadata = target.stat()
    target_identity = dependencies().scan_target_identity(target, None, metadata=target_metadata)
    revision, target_snapshot_digest, target_device, target_inode = target_identity
    scope_file_count = directory_snapshot_regular_file_count(
        target if scope == "." else target / scope
    )
    connection.execute("BEGIN IMMEDIATE")
    with connection:
        existing = existing_deep_scan_for_target(connection, thread_id, target_path, scope)
        if existing is not None:
            require_scan_checkout_owner(connection, existing)
            connection.commit()
            return begin_deep_scan_for_scan(connection, existing["id"], thread_id, args)
        current_target = dependencies().require_remediation_target(target_path)
        current_metadata = current_target.stat()
        if (current_metadata.st_dev, current_metadata.st_ino) != (
            target_metadata.st_dev,
            target_metadata.st_ino,
        ):
            raise SystemExit(
                "The selected scan target changed while the scan was starting. Try again."
            )
        terminal = terminal_deep_scan_for_target_snapshot(
            connection,
            thread_id,
            target_path,
            scope,
            user_context,
            project_path,
            revision,
            target_snapshot_digest,
            target_device,
            target_inode,
        )
        if terminal is not None:
            require_scan_checkout_owner(connection, terminal)
            connection.commit()
            return deep_scan_result(
                connection,
                terminal["id"],
                start_disposition="joined",
            )
        if args.join_only:
            return {"newScanTarget": target_path}
        source_scopes = capture_source_scopes(
            target,
            (revision, target_snapshot_digest, target_device, target_inode),
            [scope],
        )
        configuration = effective_deep_scan_config(args)
        config = configuration["settings"]
        workflow_version = optional_text(args.workflow_version, maximum=256)
        if workflow_version is None:
            raise SystemExit("workflow-version is required.")
        target_root = dependencies().scan_target_root(args.scan_root, target)
        create_private_directory(target_root, scan_output=True)
        model = optional_text(args.model, maximum=200)
        reasoning_effort = optional_text(args.reasoning_effort, maximum=32)
        workspace_id = str(uuid.uuid4())
        scan_id = str(uuid.uuid4())
        timestamp = dependencies().now()
        registration = dependencies().register_security_target(connection, target_path)
        target_id = registration.target_id
        connection.execute(
            """
            INSERT INTO workspaces (
                id, thread_id, target_id, target_path, target_title, default_scope, default_mode,
                user_context, submitted, created_at, updated_at, deep_scan_config_json
            ) VALUES (?, ?, ?, ?, ?, ?, 'deep', ?, 1, ?, ?, ?)
            """,
            (
                workspace_id,
                thread_id,
                target_id,
                target_path,
                target.name,
                scope,
                user_context,
                timestamp,
                timestamp,
                json.dumps(configuration),
            ),
        )
        workspace = connection.execute(
            "SELECT * FROM workspaces WHERE id = ?", (workspace_id,)
        ).fetchone()
        dependencies().insert_running_scan(
            connection,
            scan_id=scan_id,
            workspace=workspace,
            target=target,
            scope=scope,
            diff_target=None,
            target_identity=target_identity,
            repository_generation=registration.repository_generation,
            source_scopes=source_scopes,
            target_root=target_root,
            target_summary=None,
            scope_file_count=scope_file_count,
            timestamp=timestamp,
            handoff_status="delivered",
            model=model,
            reasoning_effort=reasoning_effort,
        )
        scan = dependencies().require_scan(connection, scan_id)
        ensure_deep_scan_run(
            connection,
            scan,
            config,
            workflow_version,
            timestamp,
            service_tier=args.service_tier,
            pending_target_project_path=project_path,
        )
    return deep_scan_result(connection, scan_id, start_disposition="created")


def begin_deep_scan(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[str, Any]:
    """Begin orchestration for a registered scan or a target, returning the scan state and its start disposition."""
    thread_id = optional_text(args.thread_id, maximum=512)
    if thread_id is None:
        raise SystemExit("thread-id is required.")
    if args.scan_id:
        if args.user_context is not None or args.user_context_stdin or args.scope != ".":
            raise SystemExit("scan-id cannot be combined with target setup fields.")
        return begin_deep_scan_for_scan(connection, args.scan_id, thread_id, args)
    if args.claim_token is not None:
        raise SystemExit("claim-token is only valid with scan-id.")
    return begin_deep_scan_for_target(connection, args, thread_id)


def get_deep_scan(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[str, Any]:
    """Return the persisted orchestration result to the thread that owns the scan."""
    scan, _ = require_owned_scan(connection, args.scan_id, args.thread_id)
    return deep_scan_result(connection, scan["id"])


def acknowledge_deep_scan_result(
    connection: sqlite3.Connection, args: argparse.Namespace
) -> dict[str, Any]:
    with connection:
        connection.execute(
            """
            UPDATE deep_scan_runs SET pending_target_project_path = NULL
            WHERE scan_id = ? AND pending_target_project_path IS NOT NULL
                AND status = 'succeeded'
                AND EXISTS (
                    SELECT 1 FROM scans WHERE id = deep_scan_runs.scan_id AND status = 'complete'
                )
            """,
            (require_uuid(args.scan_id, "scan-id"),),
        )
    return {}


def coordinator_lease_is_live(
    connection: sqlite3.Connection,
    run: sqlite3.Row,
    scan: sqlite3.Row,
    timestamp: str,
) -> bool:
    """Check coordinator freshness using the lease generation and its applicable activity timestamps."""
    if run["coordinator_generation"] == 1:
        active_worker = connection.execute(
            """
            SELECT 1 FROM deep_scan_workers
            WHERE scan_id = ? AND status IN ('queued', 'running')
            LIMIT 1
            """,
            (run["scan_id"],),
        ).fetchone()
        return active_worker is not None and _parse_timestamp(
            str(run["updated_at"])
        ) > _parse_timestamp(timestamp) - timedelta(
            seconds=DEEP_SCAN_LEGACY_COORDINATOR_GRACE_SECONDS
        )
    heartbeat_time = _parse_timestamp(str(run["updated_at"]))
    heartbeat_path = (
        Path(scan["scan_dir"])
        / "artifacts"
        / "deep_discovery"
        / f"coordinator-heartbeat-{run['coordinator_generation']}.json"
    )
    try:
        heartbeat = json.loads(heartbeat_path.read_text(encoding="utf-8"))
        if heartbeat["coordinatorGeneration"] == run["coordinator_generation"]:
            heartbeat_time = max(heartbeat_time, _parse_timestamp(heartbeat["updatedAt"]))
    except (OSError, KeyError, TypeError, ValueError):
        # Missing or invalid heartbeat files leave the persisted lease timestamp in effect.
        pass
    current_time = _parse_timestamp(timestamp)
    return heartbeat_time > current_time - timedelta(seconds=DEEP_SCAN_COORDINATOR_LEASE_SECONDS)


def require_current_coordinator(run: sqlite3.Row, args: argparse.Namespace) -> None:
    generation = getattr(args, "coordinator_generation", None)
    if run["coordinator_generation"] == 1:
        if generation is not None:
            raise SystemExit("Deep Scan coordinator lease has not been claimed.")
        return
    if generation is None:
        raise SystemExit("Deep Scan mutation requires the current coordinator lease.")
    if generation != run["coordinator_generation"]:
        raise SystemExit("Deep Scan coordinator lease belongs to a newer generation.")


def claim_deep_scan_coordinator(
    connection: sqlite3.Connection, args: argparse.Namespace
) -> dict[str, Any]:
    scan_id = require_uuid(args.scan_id, "scan-id")
    with dependencies().scan_completion_lock(scan_id):
        return claim_deep_scan_coordinator_locked(connection, args, scan_id)


def claim_deep_scan_coordinator_locked(
    connection: sqlite3.Connection, args: argparse.Namespace, scan_id: str
) -> dict[str, Any]:
    connection.execute("BEGIN IMMEDIATE")
    with connection:
        scan, _ = require_owned_scan(connection, scan_id, args.thread_id)
        require_current_continuation(
            scan,
            args.claim_token,
            error_message="Deep Scan orchestration is owned by another continuation.",
        )
        run = require_deep_scan_run(connection, scan_id)
        require_running_deep_scan(run, scan)
        timestamp = dependencies().now()
        if args.coordinator_generation is not None:
            require_current_coordinator(run, args)
            disposition = "claimed"
        elif coordinator_lease_is_live(connection, run, scan, timestamp):
            connection.commit()
            return {
                **deep_scan_result(connection, scan_id),
                "coordinatorDisposition": "observing",
            }
        else:
            adopted = run["coordinator_generation"] > 1 or run["phase"] != "setup"
            if adopted:
                recover_expired_coordinator(connection, run, timestamp)
            disposition = "adopted" if adopted else "claimed"

        connection.execute(
            """
            UPDATE deep_scan_runs
            SET coordinator_generation = coordinator_generation + ?, updated_at = ?
            WHERE scan_id = ? AND status = 'running'
            """,
            (int(args.coordinator_generation != run["coordinator_generation"]), timestamp, scan_id),
        )
    return {
        **deep_scan_result(connection, scan_id),
        "coordinatorDisposition": disposition,
    }


def recover_expired_coordinator(
    connection: sqlite3.Connection, run: sqlite3.Row, timestamp: str
) -> None:
    """Recover interrupted publications and reset active work so a replacement coordinator can resume."""
    scan_id = run["scan_id"]
    recover_candidate_ledger_publication(connection, scan_id)
    legacy_generation = int(run["coordinator_generation"] == 1)
    interrupted_discoveries = int(
        connection.execute(
            """
            SELECT COUNT(*)
            FROM deep_scan_workers
            WHERE scan_id = ? AND kind = 'discovery'
              AND (
                status IN ('queued', 'running')
                OR (
                    status = 'canceled'
                    AND (
                        error_message LIKE 'coordinator_shutdown:%'
                        OR (? = 1 AND error_message IS NULL)
                    )
                )
              )
            """,
            (scan_id, legacy_generation),
        ).fetchone()[0]
    )
    connection.execute(
        """
        UPDATE deep_scan_workers
        SET merge_state = 'buffered', updated_at = ?
        WHERE scan_id = ? AND merge_state = 'merging'
            AND id IN (
                SELECT inputs.discovery_worker_id
                FROM deep_scan_dedup_inputs AS inputs
                JOIN deep_scan_workers AS reducers ON reducers.id = inputs.dedup_worker_id
                WHERE reducers.scan_id = ?
                    AND reducers.kind = 'dedup'
                    AND (
                        reducers.status IN ('queued', 'running', 'failed')
                        OR (
                            reducers.status = 'canceled'
                            AND (
                                reducers.error_message LIKE 'coordinator_shutdown:%'
                                OR (? = 1 AND reducers.error_message IS NULL)
                            )
                        )
                    )
            )
        """,
        (timestamp, scan_id, scan_id, legacy_generation),
    )
    cancel_active_workers(connection, scan_id, timestamp)
    connection.execute(
        """
        UPDATE deep_scan_workers
        SET error_message = 'coordinator_shutdown_recovered: replacement attempt required',
            updated_at = ?
        WHERE scan_id = ? AND status = 'canceled'
            AND (
                error_message LIKE 'coordinator_shutdown:%'
                OR (? = 1 AND error_message IS NULL)
            )
        """,
        (timestamp, scan_id, legacy_generation),
    )
    connection.execute(
        """
        UPDATE deep_scan_runs
        SET discovery_runs_dispatched = discovery_runs_dispatched - ?,
            phase = CASE WHEN phase = 'setup' THEN 'setup' ELSE 'discovery' END,
            updated_at = ?
        WHERE scan_id = ?
        """,
        (interrupted_discoveries, timestamp, scan_id),
    )


def recover_candidate_ledger_publication(connection: sqlite3.Connection, scan_id: str) -> None:
    """Reconcile ledger backups with reducer snapshots after an interrupted publication."""
    scan = dependencies().require_scan(connection, scan_id)
    ledger = Path(scan["scan_dir"]) / "artifacts" / "02_discovery" / "candidate_ledger.jsonl"
    backups = sorted(
        ledger.parent.glob(f".{ledger.name}.*.backup"),
        key=lambda backup: backup.stat().st_mtime_ns,
        reverse=True,
    )
    if not ledger.exists() and not backups:
        return
    reducers = connection.execute(
        """
        SELECT status, artifact_dir
        FROM deep_scan_workers
        WHERE scan_id = ? AND kind = 'dedup'
          AND status IN ('queued', 'running', 'succeeded')
        ORDER BY updated_at DESC
        """,
        (scan_id,),
    )
    for reducer in reducers:
        snapshot = Path(reducer["artifact_dir"]) / "canonical" / ledger.name
        if not snapshot.exists():
            continue
        published = publication_matches_snapshot(ledger, snapshot)
        interrupted = reducer["status"] != "succeeded"
        if not published and not (interrupted and backups and not ledger.exists()):
            continue
        if interrupted:
            if backups:
                os.replace(backups.pop(0), ledger)
            else:
                ledger.unlink(missing_ok=True)
        for backup in backups:
            backup.unlink(missing_ok=True)
        return


def require_running_deep_scan(run: sqlite3.Row, scan: sqlite3.Row) -> None:
    if run["status"] != "running" or run["cancel_requested"]:
        raise SystemExit("Only a running Deep Scan can update orchestration state.")
    if scan["status"] != "running" or scan["canceled_at"] is not None:
        raise SystemExit("Only a running scan can update Deep Scan orchestration state.")


def require_worker_transition(current: str, requested: str) -> None:
    allowed = {
        "queued": {"queued", "running", "failed", "canceled"},
        "running": {"running", "succeeded", "failed", "canceled"},
        "succeeded": {"succeeded"},
        "failed": {"failed"},
        "canceled": {"canceled"},
    }
    if requested not in allowed[current]:
        raise SystemExit(f"Deep Scan worker cannot transition from {current} to {requested}.")


def upsert_deep_scan_worker(
    connection: sqlite3.Connection, args: argparse.Namespace
) -> dict[str, Any]:
    scan_id = require_uuid(args.scan_id, "scan-id")
    worker_id = require_uuid(args.worker_id, "worker-id")
    connection.execute("BEGIN IMMEDIATE")
    with connection:
        run = require_deep_scan_run(connection, scan_id)
        require_current_coordinator(run, args)
        scan = dependencies().require_scan(connection, scan_id)
        existing = connection.execute(
            "SELECT * FROM deep_scan_workers WHERE id = ?", (worker_id,)
        ).fetchone()
        if args.terminal_failure and (
            args.status != "failed" or not optional_text(args.error_message)
        ):
            raise SystemExit(
                "A terminal worker failure requires failed status and an error message."
            )
        replaceable_failure_kind = args.replaceable_failure_kind
        if replaceable_failure_kind is not None and (
            args.kind != "discovery"
            or args.status != "canceled"
            or existing is None
            or existing["status"] not in {"running", "canceled"}
            or optional_text(args.error_message) is None
        ):
            raise SystemExit(
                "A replaceable Deep Scan failure requires a running discovery worker, "
                "canceled status, and an error message."
            )
        cleanup_update = (
            existing is not None
            and args.status == "canceled"
            and existing["status"] in {"queued", "running", "canceled"}
            and run["status"] in {"succeeded", "failed", "canceled", "interrupted"}
        )
        terminal_repeat = (
            existing is not None
            and existing["status"] == args.status
            and args.status in {"succeeded", "failed", "canceled"}
        )
        if not cleanup_update and not terminal_repeat:
            require_running_deep_scan(run, scan)
        prompt_path = deep_scan_path(scan, args.prompt_path, "Worker prompt path", kind="file")
        artifact_dir = deep_scan_path(
            scan, args.artifact_dir, "Worker artifact directory", kind="directory"
        )
        result_manifest_path = (
            deep_scan_path(
                scan,
                args.result_manifest_path,
                "Worker result manifest path",
                kind="file",
            )
            if args.result_manifest_path
            else None
        )
        timestamp = dependencies().now()
        if existing is None:
            if args.kind == "dedup":
                raise SystemExit(
                    "Deep Scan checkpoints are recorded with record-deep-scan-iteration."
                )
            if args.status not in {"queued", "running"}:
                raise SystemExit("A new Deep Scan worker must be queued or running.")
            if (
                args.kind == "setup"
                and connection.execute(
                    "SELECT 1 FROM deep_scan_workers WHERE scan_id = ? AND kind = 'setup'",
                    (scan_id,),
                ).fetchone()
                is not None
            ):
                raise SystemExit("A Deep Scan can have only one setup worker.")
            attempt = (
                args.attempt if args.attempt is not None else (1 if args.status == "running" else 0)
            )
            if args.status == "running" and attempt < 1:
                raise SystemExit("A running Deep Scan worker attempt must be at least one.")
            if args.kind == "discovery":
                if run["discovery_runs_dispatched"] >= run["max_discovery_runs"]:
                    raise SystemExit("Deep Scan maximum discovery runs has been reached.")
                connection.execute(
                    """
                    UPDATE deep_scan_runs
                    SET discovery_runs_dispatched = discovery_runs_dispatched + 1,
                        phase = 'discovery', updated_at = ?
                    WHERE scan_id = ?
                    """,
                    (timestamp, scan_id),
                )
            connection.execute(
                """
                INSERT INTO deep_scan_workers (
                    id, scan_id, kind, status, prompt_path, artifact_dir, attempt,
                    sdk_thread_id, error_message, created_at, started_at, updated_at
                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
                """,
                (
                    worker_id,
                    scan_id,
                    args.kind,
                    args.status,
                    prompt_path,
                    artifact_dir,
                    attempt,
                    optional_text(args.sdk_thread_id, maximum=512),
                    optional_text(args.error_message),
                    timestamp,
                    timestamp if args.status == "running" else None,
                    timestamp,
                ),
            )
            connection.commit()
            return deep_scan_result(connection, scan_id)

        if existing["scan_id"] != scan_id or existing["kind"] != args.kind:
            raise SystemExit("Deep Scan worker identity does not match its persisted run and kind.")
        if existing["prompt_path"] != prompt_path or existing["artifact_dir"] != artifact_dir:
            raise SystemExit("Deep Scan worker prompt and artifact paths are immutable.")
        require_worker_transition(existing["status"], args.status)
        if terminal_repeat:
            repeated_attempt = args.attempt if args.attempt is not None else existing["attempt"]
            repeated_thread_id = optional_text(args.sdk_thread_id, maximum=512)
            repeated_error = optional_text(args.error_message)
            repeated_result_path = result_manifest_path or existing["result_manifest_path"]
            if (
                repeated_attempt != existing["attempt"]
                or repeated_result_path != existing["result_manifest_path"]
                or (
                    repeated_thread_id is not None
                    and repeated_thread_id != existing["sdk_thread_id"]
                )
                or repeated_error is not None
                and repeated_error != existing["error_message"]
            ):
                raise SystemExit("Deep Scan worker terminal state is immutable.")
            connection.commit()
            return deep_scan_result(connection, scan_id)
        attempt = args.attempt if args.attempt is not None else existing["attempt"]
        if attempt < existing["attempt"]:
            raise SystemExit("Deep Scan worker attempt cannot decrease.")
        if args.status == "running" and attempt < 1:
            raise SystemExit("A running Deep Scan worker attempt must be at least one.")
        if args.kind == "dedup" and args.status == "succeeded":
            raise SystemExit("Deep Scan checkpoints are recorded with record-deep-scan-iteration.")
        if args.kind == "discovery" and args.status == "succeeded" and result_manifest_path is None:
            result_manifest_path = existing["result_manifest_path"]
            if result_manifest_path is None:
                raise SystemExit("A successful Deep Scan worker requires a result manifest.")

        completion_sequence = existing["completion_sequence"]
        merge_state = existing["merge_state"]
        if args.kind == "discovery" and args.status == "succeeded" and completion_sequence is None:
            completion_sequence = run["completion_sequence"] + 1
            merge_state = "buffered"
            connection.execute(
                """
                UPDATE deep_scan_runs
                SET completion_sequence = ?, phase = 'discovery',
                    consecutive_errors = 0, updated_at = ?
                WHERE scan_id = ?
                """,
                (completion_sequence, timestamp, scan_id),
            )
        elif (
            args.kind == "discovery"
            and args.status == "canceled"
            and replaceable_failure_kind is not None
            and existing["status"] == "running"
        ):
            connection.execute(
                """
                UPDATE deep_scan_runs
                SET consecutive_errors = consecutive_errors + 1, updated_at = ?
                WHERE scan_id = ?
                """,
                (timestamp, scan_id),
            )
        elif args.kind == "dedup" and args.status == "failed" and existing["status"] == "running":
            connection.execute(
                """
                UPDATE deep_scan_workers
                SET merge_state = 'buffered', updated_at = ?
                WHERE scan_id = ? AND kind = 'discovery' AND status = 'succeeded'
                    AND merge_state = 'merging'
                    AND id IN (
                        SELECT discovery_worker_id FROM deep_scan_dedup_inputs
                        WHERE scan_id = ? AND dedup_worker_id = ?
                    )
                """,
                (timestamp, scan_id, scan_id, worker_id),
            )
            connection.execute(
                """
                UPDATE deep_scan_runs
                SET phase = 'discovery', updated_at = ?
                WHERE scan_id = ?
                """,
                (timestamp, scan_id),
            )
        completed_at = (
            timestamp
            if args.status in {"succeeded", "failed", "canceled"}
            else existing["completed_at"]
        )
        error_message = optional_text(args.error_message)
        if error_message is None and args.status != "succeeded":
            error_message = existing["error_message"]
        started_at = existing["started_at"] or (timestamp if args.status == "running" else None)
        thread_id = optional_text(args.sdk_thread_id, maximum=512)
        if thread_id is None and attempt == existing["attempt"]:
            thread_id = existing["sdk_thread_id"]
        connection.execute(
            """
            UPDATE deep_scan_workers
            SET status = ?, result_manifest_path = ?, attempt = ?,
                sdk_thread_id = ?,
                completion_sequence = ?, merge_state = ?,
                error_message = ?,
                started_at = ?, completed_at = ?, updated_at = ?
            WHERE id = ?
            """,
            (
                args.status,
                result_manifest_path or existing["result_manifest_path"],
                attempt,
                thread_id,
                completion_sequence,
                merge_state,
                error_message,
                started_at,
                completed_at,
                timestamp,
                worker_id,
            ),
        )
        if args.terminal_failure:
            # Persist the first terminal cause with its worker. An adopting coordinator
            # completes the normal failure path after active workers have settled.
            connection.execute(
                "UPDATE deep_scan_runs SET error_message = ? WHERE scan_id = ? AND error_message IS NULL",
                (error_message, scan_id),
            )
    return deep_scan_result(connection, scan_id)


def record_deep_scan_iteration(
    connection: sqlite3.Connection, args: argparse.Namespace
) -> dict[str, Any]:
    """Commit the checkpoint and its input workers in one transaction, then return deep scan state.

    Repeating the same iteration and inputs replays the saved result. Conflicting
    checkpoint or input-worker IDs raise SystemExit.
    """
    scan_id = require_uuid(args.scan_id, "scan-id")
    checkpoint_id = require_uuid(args.worker_id, "worker-id")
    input_ids = [require_uuid(value, "input-worker-id") for value in args.input_worker_id]
    connection.execute("BEGIN IMMEDIATE")
    with connection:
        run = require_deep_scan_run(connection, scan_id)
        scan = dependencies().require_scan(connection, scan_id)
        require_running_deep_scan(run, scan)
        require_current_coordinator(run, args)
        result = deep_scan_path(scan, args.result_manifest_path, "Iteration result", kind="file")
        existing = connection.execute(
            "SELECT scan_id, result_manifest_path FROM deep_scan_workers WHERE id = ?",
            (checkpoint_id,),
        ).fetchone()
        if existing is not None:
            if existing["scan_id"] != scan_id or existing["result_manifest_path"] != result:
                raise SystemExit("Iteration already belongs to another result.")
            recorded_ids = [
                row[0]
                for row in connection.execute(
                    "SELECT discovery_worker_id FROM deep_scan_dedup_inputs WHERE dedup_worker_id = ? ORDER BY input_order",
                    (checkpoint_id,),
                )
            ]
            if recorded_ids != input_ids:
                raise SystemExit("Iteration already belongs to other completed scans.")
            return deep_scan_result(connection, scan_id)
        now = dependencies().now()
        # Historical scans use the same rows to bind the selected aggregate at publication.
        connection.execute(
            """INSERT INTO deep_scan_workers
               (id, scan_id, kind, status, prompt_path, artifact_dir, result_manifest_path,
                created_at, completed_at, updated_at)
               VALUES (?, ?, 'dedup', 'succeeded', ?, ?, ?, ?, ?, ?)""",
            (checkpoint_id, scan_id, result, str(Path(result).parent), result, now, now, now),
        )
        for index, worker_id in enumerate(input_ids):
            updated = connection.execute(
                """UPDATE deep_scan_workers SET merge_state = 'merged', updated_at = ?
                   WHERE scan_id = ? AND id = ? AND kind = 'discovery'
                   AND status = 'succeeded' AND merge_state = 'buffered'""",
                (now, scan_id, worker_id),
            )
            if updated.rowcount != 1:
                raise SystemExit("Iteration input is not an unmerged completed scan.")
            connection.execute(
                "INSERT INTO deep_scan_dedup_inputs VALUES (?, ?, ?, ?)",
                (scan_id, checkpoint_id, worker_id, index),
            )
        connection.execute(
            "UPDATE deep_scan_runs SET phase = 'discovery', consecutive_no_new = ?, consecutive_errors = ?, updated_at = ? WHERE scan_id = ?",
            (args.no_new_streak, args.consecutive_errors, now, scan_id),
        )
        connection.execute(
            "UPDATE scan_progress SET deep_review_pass = COALESCE(deep_review_pass, 0) + 1, updated_at = ? WHERE scan_id = ?",
            (now, scan_id),
        )
    return deep_scan_result(connection, scan_id)


def finish_deep_scan(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[str, Any]:
    scan_id = require_uuid(args.scan_id, "scan-id")
    with dependencies().scan_completion_lock(scan_id):
        return finish_deep_scan_locked(connection, args, scan_id)


def finish_deep_scan_locked(
    connection: sqlite3.Connection, args: argparse.Namespace, scan_id: str
) -> dict[str, Any]:
    omitted_worker_ids = {
        require_uuid(value, "omitted-worker-id") for value in args.omitted_worker_id
    }
    if len(omitted_worker_ids) != len(args.omitted_worker_id):
        raise SystemExit("Omitted Deep Scan worker IDs must be unique.")
    promotion: tuple[Path, Path, Path | None] | None = None
    deadline_publication: (
        tuple[Path, dict[str, tuple[bytes, os.stat_result] | None], set[str]] | None
    ) = None
    connection.execute("BEGIN IMMEDIATE")
    try:
        run = require_deep_scan_run(connection, scan_id)
        require_current_coordinator(run, args)
        scan = dependencies().require_scan(connection, scan_id)
        manifest_path = (
            deep_scan_output_path(scan, args.manifest_path, "Deep Scan coordinator manifest path")
            if args.staged_manifest_path
            else deep_scan_path(
                scan, args.manifest_path, "Deep Scan coordinator manifest path", kind="file"
            )
        )
        standard_scan_manifest = manifest_path == str(Path(scan["scan_dir"]) / "scan-manifest.json")

        buffered_worker_ids = {
            row["id"]
            for row in connection.execute(
                """
                SELECT id
                FROM deep_scan_workers
                WHERE scan_id = ? AND kind = 'discovery' AND merge_state = 'buffered'
                """,
                (scan_id,),
            )
        }
        if run["status"] == "succeeded":
            if (
                run["terminal_reason"] != args.terminal_reason
                or archived_deep_path(Path(scan["scan_dir"]), run["manifest_path"])
                not in {None, manifest_path}
                or omitted_worker_ids != buffered_worker_ids
            ):
                raise SystemExit(
                    "Deep Scan terminal state is immutable; finish must exactly replay its "
                    "terminal reason, manifest path, and omitted worker IDs."
                )
            if run["manifest_path"] is None:
                connection.execute(
                    "UPDATE deep_scan_runs SET manifest_path = ?, updated_at = ? WHERE scan_id = ?",
                    (manifest_path, dependencies().now(), scan_id),
                )
            connection.commit()
            return deep_scan_result(connection, scan_id)
        require_running_deep_scan(run, scan)
        if run["error_message"] is not None:
            raise SystemExit(run["error_message"])
        if (
            args.terminal_reason == "saturated"
            and run["consecutive_no_new"] < run["stop_after_no_new"]
        ):
            raise SystemExit(
                "Deep Scan cannot finish saturated before reaching its no-new-findings threshold."
            )
        if (
            args.terminal_reason == "capped"
            and run["discovery_runs_dispatched"] < run["max_discovery_runs"]
            and not deep_scan_deadline_reached(run)
        ):
            raise SystemExit(
                "Deep Scan cannot finish capped before reaching its configured maximum."
            )
        canonical_artifacts = None
        if standard_scan_manifest:
            for artifact_name in ("scan-manifest.json", "findings.json"):
                deep_scan_path(
                    scan,
                    str(Path(scan["scan_dir"]) / artifact_name),
                    f"Canonical parent {artifact_name}",
                    kind="file",
                )
        else:
            try:
                canonical_artifacts = canonical_discovery_artifacts(scan)
            except SystemExit as exc:
                raise SystemExit(
                    f"Deep Scan cannot finish without canonical discovery artifacts: {exc}"
                ) from exc
        saved_iteration = connection.execute(
            """
            SELECT 1 FROM deep_scan_workers
            WHERE scan_id = ? AND kind = 'dedup' AND status = 'succeeded'
            LIMIT 1
            """,
            (scan_id,),
        ).fetchone()
        discovery_deadline = args.terminal_reason == "capped" and deep_scan_deadline_reached(run)
        zero_discovery_deadline = (
            discovery_deadline
            and run["completion_sequence"] == 0
            and (
                standard_scan_manifest
                or canonical_artifacts is not None
                and Path(canonical_artifacts["candidateLedgerPath"]).stat().st_size == 0
            )
        )
        if saved_iteration is None and not zero_discovery_deadline:
            raise SystemExit("Deep Scan cannot finish without a saved iteration.")
        if args.terminal_reason == "saturated":
            # Saturation cancels surplus workers, including failed cancellation writes.
            cancel_active_workers(connection, scan_id, dependencies().now())
        require_deep_scan_workers_finished(
            connection,
            scan_id,
            args.terminal_reason,
            has_omitted_workers=bool(omitted_worker_ids),
        )
        if args.terminal_reason == "saturated" and omitted_worker_ids != buffered_worker_ids:
            raise SystemExit(
                f"Deep Scan {args.terminal_reason} completion must exactly identify all buffered discovery "
                "workers with --omitted-worker-id."
            )
        if args.staged_manifest_path:
            staged_manifest_path = deep_scan_path(
                scan,
                args.staged_manifest_path,
                "Staged Deep Scan coordinator manifest path",
                kind="file",
            )
            promotion = promote_staged_file(staged_manifest_path, manifest_path)
        if zero_discovery_deadline or (discovery_deadline and standard_scan_manifest):
            deadline_publication = saved_results.preserve_deep_deadline_draft(
                dependencies(),
                connection,
                scan,
                preserve_reduction=not zero_discovery_deadline,
                allow_empty=not standard_scan_manifest,
            )
        timestamp = dependencies().now()
        connection.execute(
            """
            UPDATE deep_scan_runs
            SET status = 'succeeded', phase = 'terminal', terminal_reason = ?,
                manifest_path = ?, completed_at = ?, updated_at = ?
            WHERE scan_id = ?
            """,
            (args.terminal_reason, manifest_path, timestamp, timestamp, scan_id),
        )
        connection.commit()
    except BaseException:
        connection.rollback()
        if deadline_publication is not None or promotion is not None:
            # A signal can arrive after SQLite commits but before commit returns.
            # The completion lock makes persisted success authoritative here.
            if require_deep_scan_run(connection, scan_id)["status"] == "succeeded":
                if promotion is not None:
                    finish_staged_file(promotion)
                raise
        if deadline_publication is not None:
            saved_results._restore_published_outputs(*deadline_publication)
        if promotion is not None:
            rollback_staged_file(promotion)
        raise
    if promotion is not None:
        finish_staged_file(promotion)
    return deep_scan_result(connection, scan_id)


def fail_deep_scan(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[str, Any]:
    scan_id = require_uuid(args.scan_id, "scan-id")
    with dependencies().scan_completion_lock(scan_id):
        return fail_deep_scan_locked(connection, args, scan_id)


def fail_deep_scan_locked(
    connection: sqlite3.Connection, args: argparse.Namespace, scan_id: str
) -> dict[str, Any]:
    message = optional_text(args.message)
    if message is None:
        raise SystemExit("message is required.")
    promotion: tuple[Path, Path, Path | None] | None = None
    connection.execute("BEGIN IMMEDIATE")
    try:
        run = require_deep_scan_run(connection, scan_id)
        require_current_coordinator(run, args)
        scan = dependencies().require_scan(connection, scan_id)
        recorded_manifest = archived_deep_path(Path(scan["scan_dir"]), run["manifest_path"])
        manifest_path = None
        if args.manifest_path:
            manifest_path = (
                deep_scan_output_path(scan, args.manifest_path, "Deep Scan failure manifest path")
                if args.staged_manifest_path
                else deep_scan_path(
                    scan,
                    args.manifest_path,
                    "Deep Scan failure manifest path",
                    kind="file",
                )
            )
        elif recorded_manifest == str(Path(scan["scan_dir"]) / "scan-manifest.json"):
            manifest_path = recorded_manifest
        if run["status"] in {"failed", "interrupted"} or scan["status"] == "failed":
            if (
                run["status"] == args.deep_status
                and scan["status"] == "failed"
                and run["error_message"] == message
                and recorded_manifest == manifest_path
                and scan["failure_message"] == message
            ):
                connection.commit()
                return deep_scan_result(connection, scan_id)
            raise SystemExit(
                "Deep Scan terminal failure state is immutable; failure status, message, "
                "manifest path, and parent failure must exactly match."
            )
        terminal_before_manifest = (
            args.deep_status in {"failed", "interrupted"}
            and run["status"] == "succeeded"
            and run["terminal_reason"] in {"saturated", "capped"}
            and run["manifest_path"] is None
        )
        if (run["status"] != "running" and not terminal_before_manifest) or scan[
            "status"
        ] != "running":
            raise SystemExit("Only a running Deep Scan can be failed or interrupted.")
        # Cleanup can report a later error after a worker committed the terminal cause.
        if run["status"] == "running" and run["error_message"] is not None:
            message = run["error_message"]
        if run["manifest_path"] not in {None, manifest_path}:
            raise SystemExit("Deep Scan coordinator manifest path is immutable.")
        if args.staged_manifest_path and manifest_path:
            staged_manifest_path = deep_scan_path(
                scan,
                args.staged_manifest_path,
                "Staged Deep Scan failure manifest path",
                kind="file",
            )
            promotion = promote_staged_file(staged_manifest_path, manifest_path)
        timestamp = dependencies().now()
        connection.execute(
            """
            UPDATE deep_scan_runs
            SET status = ?, phase = 'terminal', cancel_requested = 1,
                error_message = ?, manifest_path = ?, completed_at = ?, updated_at = ?
            WHERE scan_id = ?
            """,
            (args.deep_status, message, manifest_path, timestamp, timestamp, scan_id),
        )
        cancel_active_workers(connection, scan_id, timestamp)
        if not saved_results.mark_running_scan_failed(connection, scan_id, message, timestamp):
            raise SystemExit("Deep Scan failure could not be persisted to its parent scan.")
        saved_results.touch_scan_progress(connection, scan_id, timestamp)
        connection.commit()
    except BaseException:
        connection.rollback()
        if promotion is not None:
            rollback_staged_file(promotion)
        raise
    if promotion is not None:
        finish_staged_file(promotion)
    dependencies().preserve_stopped_results(connection, scan_id)
    return deep_scan_result(connection, scan_id)


def record_deep_scan_publication_failure(
    connection: sqlite3.Connection, args: argparse.Namespace
) -> dict[str, Any]:
    scan_id = require_uuid(args.scan_id, "scan-id")
    message = optional_text(args.message)
    if message is None:
        raise SystemExit("message is required.")
    with dependencies().scan_completion_lock(scan_id):
        connection.execute("BEGIN IMMEDIATE")
        with connection:
            run = require_deep_scan_run(connection, scan_id)
            require_current_coordinator(run, args)
            scan = dependencies().require_scan(connection, scan_id)
            if (
                run["status"] not in {"failed", "canceled", "interrupted"}
                or scan["status"] != "failed"
            ):
                raise SystemExit(
                    "Saved result publication failures can only update a stopped Deep Scan."
                )
            if scan["seal_manifest_digest"] is not None:
                connection.commit()
                return deep_scan_result(connection, scan_id)
            if run["publication_error_message"] != message:
                timestamp = dependencies().now()
                connection.execute(
                    """
                    UPDATE deep_scan_runs
                    SET publication_error_message = ?, updated_at = ?
                    WHERE scan_id = ?
                    """,
                    (message, timestamp, scan_id),
                )
    return deep_scan_result(connection, scan_id)


def clear_deep_scan_publication_failure(connection: sqlite3.Connection, scan_id: str) -> None:
    with connection:
        connection.execute(
            "UPDATE deep_scan_runs SET publication_error_message = NULL, updated_at = ? "
            "WHERE scan_id = ? AND publication_error_message IS NOT NULL",
            (dependencies().now(), scan_id),
        )


def fail_from_parent_scan(
    connection: sqlite3.Connection,
    scan_id: str,
    message: str | None,
    timestamp: str,
) -> None:
    # Parent failure may supersede a prepared seal even after the coordinator succeeded.
    connection.execute(
        "UPDATE deep_scan_runs SET terminal_reviewed_surface_count = NULL WHERE scan_id = ?",
        (scan_id,),
    )
    connection.execute(
        """
        UPDATE deep_scan_runs
        SET status = 'failed', phase = 'terminal', cancel_requested = 1,
            error_message = ?, completed_at = ?, updated_at = ?
        WHERE scan_id = ? AND status = 'running'
        """,
        (message, timestamp, timestamp, scan_id),
    )
    cancel_active_workers(connection, scan_id, timestamp)


def cancel_from_parent_scan(connection: sqlite3.Connection, scan_id: str, timestamp: str) -> None:
    connection.execute(
        """
        UPDATE deep_scan_runs
        SET status = 'canceled', phase = 'terminal', cancel_requested = 1, error_message = NULL,
            terminal_reviewed_surface_count = NULL, completed_at = ?, updated_at = ?
        WHERE scan_id = ? AND status IN ('running', 'succeeded')
        """,
        (timestamp, timestamp, scan_id),
    )
    cancel_active_workers(connection, scan_id, timestamp)


def cancel_active_workers(connection: sqlite3.Connection, scan_id: str, timestamp: str) -> None:
    connection.execute(
        """
        UPDATE deep_scan_workers
        SET status = 'canceled', completed_at = ?, updated_at = ?
        WHERE scan_id = ? AND status IN ('queued', 'running')
        """,
        (timestamp, timestamp, scan_id),
    )


def other_running_deep_scans(
    connection: sqlite3.Connection, current_scan_id: str
) -> list[dict[str, str]]:
    """List other running Deep Scans ordered by most recent update, with target paths and phases."""
    rows = connection.execute(
        """
        SELECT id, target_path, phase, started_at, updated_at
        FROM scans
        WHERE mode = 'deep' AND status = 'running' AND id != ?
        ORDER BY updated_at DESC, started_at DESC, id
        """,
        (current_scan_id,),
    )
    return [
        {
            "phase": row["phase"],
            "scanId": row["id"],
            "startedAt": row["started_at"],
            "targetPath": row["target_path"],
            "updatedAt": row["updated_at"],
        }
        for row in rows
    ]


if __name__ == "__main__":
    argparse.ArgumentParser(description=__doc__).parse_args()

SHA-256: d5f65879341d97d18f531fae0ce197e11207761add9787c2c0031f2980dca6d9