← Files ClaraARCHIVED FILE

modules/studio-archive/scripts/studio_archive.py

31 KB · Nov 21, 2026 · 00:11 UTC

↓ Download file

See the change to this file →

#!/usr/bin/env python3
"""Command-line interface for Vera Studio Archive."""

from __future__ import annotations

import argparse
import json
import logging
import os
import sqlite3
import sys
from contextlib import ExitStack
from pathlib import Path
from typing import Any

# Check before importing the worker and its dependencies so an unsupported
# interpreter reports the launch error instead of failing on a newer API.
if sys.implementation.name != "cpython" or sys.version_info[:2] != (3, 12):
    logging.error("Studio Archive requires CPython 3.12; use its managed launcher.")
    sys.stdout.write(
        json.dumps(
            {
                "error": {
                    "code": "unsupported_python_runtime",
                    "message": (
                        "Studio Archive requires CPython 3.12; running "
                        f"{sys.implementation.name} {sys.version.split()[0]} at "
                        f"{sys.executable}. Launch through "
                        "scripts/managed_python_runtime.py --module studio-archive "
                        "run scripts/studio_archive.py."
                    ),
                }
            }
        )
        + "\n"
    )
    raise SystemExit(1)

from archive_core import (
    CLIENT_WORKFLOW_IDS,
    VERA_CLIENT_WORKFLOW_IDS,
    ArchiveError,
    authorize_studio_google_drive,
    begin_studio_incarico,
    bind_studio_client_google_drive,
    cancel_studio_client_workflow,
    check_studio_import_sources,
    checkpoint_studio_client_workflow,
    close_studio_client_engagement,
    complete_studio_client_workflow,
    configure_archive,
    copy_studio_client_source_folder,
    create_studio_client,
    create_studio_client_engagement,
    diagnose_archive_access,
    fail_studio_client_workflow,
    finalize_studio_client_workflow,
    get_studio_archive_organization_inventory,
    get_studio_client_folder,
    get_studio_incarico,
    import_studio_client_document,
    list_studio_client_engagements,
    list_studio_clients,
    map_studio_legacy_incarichi,
    match_studio_email_client,
    normalize_studio_archive_layout,
    open_archive_source,
    open_studio_archive_organization_item,
    plan_gmail_client_search,
    prepare_studio_client_workflow,
    publish_studio_incarico_result,
    read_studio_incarico_document,
    read_studio_run_artifact,
    recover_studio_client_ledger,
    refresh_archive,
    report_studio_client_retention,
    resolve_studio_client_identity,
    restore_studio_client_workflow,
    reuse_studio_incarico_result,
    search_archive,
    set_studio_client_identity,
    setup_archive_with_folder_picker,
    snapshot_studio_client_folder,
    snapshot_studio_client_google_drive,
    start_check_entries_from_sample,
    start_studio_client_workflow,
    studio_archive_status,
    studio_google_drive_status,
    update_studio_incarico,
    use_studio_run_context,
    verify_studio_client_inputs,
    verify_studio_run_report,
    write_studio_run_artifact,
)
from archive_error_reporting import record_error

__all__ = ["main"]


def _emit(payload: dict[str, Any]) -> None:
    # JSON escapes preserve every decoded value on ASCII/legacy Windows pipes.
    sys.stdout.write(json.dumps(payload, ensure_ascii=True, sort_keys=True) + "\n")


def _parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument(
        "--context",
        type=Path,
        help="Verified saved context; use before the command when Archive lookup is unavailable",
    )
    subparsers = parser.add_subparsers(dest="command", required=True)

    subparsers.add_parser("record-error", help=argparse.SUPPRESS)

    subparsers.add_parser("setup")

    configure = subparsers.add_parser("configure")
    configure.add_argument("--archive-root", type=Path, required=True)
    configure.add_argument("--make-studio-default", action="store_true")
    configure.add_argument(
        "--host-folder-access-approved",
        action="store_true",
        help=argparse.SUPPRESS,
    )

    diagnose_access = subparsers.add_parser("diagnose-access")
    diagnose_access.add_argument("--archive-root", type=Path, required=True)
    diagnose_access.add_argument(
        "--host-folder-access-approved",
        action="store_true",
        help=argparse.SUPPRESS,
    )

    subparsers.add_parser("status")
    subparsers.add_parser("clients")
    subparsers.add_parser("normalize-project-layout")

    resolve_client = subparsers.add_parser("resolve-client")
    resolve_client.add_argument(
        "--identity-kind",
        choices=["email_address", "legal_name", "tax_identifier"],
        required=True,
    )
    resolve_client.add_argument("--identity-value", required=True)

    client_folder = subparsers.add_parser("client-folder")
    client_folder.add_argument("--client-id", required=True)

    create_client = subparsers.add_parser("create-client")
    create_client.add_argument("--legal-name", required=True)
    create_client.add_argument("--general-workspace", action="store_true")
    create_client.add_argument("--email-address", action="append", default=[])
    create_client.add_argument("--tax-identifier", action="append", default=[])

    create_engagement = subparsers.add_parser("create-engagement")
    create_engagement.add_argument("--client-id", required=True)
    create_engagement.add_argument("--engagement-label", required=True)
    create_engagement.add_argument("--idempotency-key")

    check_sources = subparsers.add_parser("check-import-sources")
    check_sources.add_argument(
        "--source-path", type=Path, action="append", required=True
    )
    check_sources.add_argument("--expected-sha256", action="append")

    import_document = subparsers.add_parser("import-document")
    import_document.add_argument("--client-id", required=True)
    import_document.add_argument("--source-path", type=Path, required=True)
    import_document.add_argument(
        "--role", choices=["journal", "source", "support"], required=True
    )
    import_document.add_argument("--engagement-id", required=True)
    import_document.add_argument("--expected-sha256")

    copy_folder = subparsers.add_parser("copy-client-source-folder")
    copy_folder.add_argument("--client-id", required=True)
    copy_folder.add_argument("--engagement-id", required=True)
    copy_folder.add_argument("--source-path", type=Path, required=True)
    copy_folder.add_argument("--destination-name")
    copy_folder.add_argument("--copy-authorized", action="store_true", required=True)

    engagements = subparsers.add_parser("engagements")
    engagements.add_argument("--client-id", required=True)

    verification = subparsers.add_parser("verify-inputs")
    verification.add_argument("--client-id", required=True)
    verification.add_argument("--engagement-id", required=True)
    verification.add_argument("--input-id", action="append", required=True)
    verification.add_argument("--expected-receipts-json")
    verification.add_argument("--require-exact-input-set", action="store_true")

    snapshot_folder = subparsers.add_parser("snapshot-client-folder")
    snapshot_folder.add_argument("--client-id", required=True)
    snapshot_folder.add_argument("--engagement-id", required=True)

    authorize_drive = subparsers.add_parser("authorize-google-drive")
    authorize_drive.add_argument("--client-secrets", type=Path, required=True)

    subparsers.add_parser("google-drive-status")

    bind_drive = subparsers.add_parser("bind-google-drive")
    bind_drive.add_argument("--client-id", required=True)
    bind_drive.add_argument("--folder-id", required=True)

    snapshot_drive = subparsers.add_parser("snapshot-google-drive")
    snapshot_drive.add_argument("--client-id", required=True)
    snapshot_drive.add_argument("--engagement-id", required=True)

    inventory = subparsers.add_parser("archive-organization-inventory")
    inventory.add_argument("--client-id", required=True)
    inventory.add_argument("--engagement-id", required=True)
    inventory.add_argument("--snapshot-input-id", required=True)

    open_item = subparsers.add_parser("open-archive-organization-item")
    open_item.add_argument("--client-id", required=True)
    open_item.add_argument("--engagement-id", required=True)
    open_item.add_argument("--snapshot-input-id", required=True)
    open_item.add_argument("--item-ref", required=True)

    incarico = subparsers.add_parser("incarico")
    incarico.add_argument("--client-id", required=True)
    incarico.add_argument("--engagement-id", required=True)
    incarico.add_argument(
        "--fields-json", help="Complete assignment fields; omit for read-only"
    )
    incarico.add_argument("--expected-revision", default="")
    map_legacy = subparsers.add_parser("map-legacy-incarichi")
    for flag in ("client-id", "engagement-id", "targets-json"):
        map_legacy.add_argument("--" + flag, required=True)
    open_incarico = subparsers.add_parser("open-incarico-document")
    for flag in ("client-id", "engagement-id", "reference-json"):
        open_incarico.add_argument("--" + flag, required=True)
    begin_incarico = subparsers.add_parser("begin-incarico")
    for flag in ("client-id", "engagement-id", "workflow-id", "purpose"):
        begin_incarico.add_argument("--" + flag, required=True)
    begin_incarico.add_argument("--originating-conversation-json")
    publish_result = subparsers.add_parser("publish-incarico-result")
    for flag in (
        "client-id",
        "engagement-id",
        "entry-key",
        "label",
        "files-json",
        "idempotency-key",
    ):
        publish_result.add_argument("--" + flag, required=True)
    publish_result.add_argument("--expected-revision", type=int, required=True)
    publish_result.add_argument("--primary-format")
    reuse_result = subparsers.add_parser("reuse-incarico-result")
    for flag in ("client-id", "engagement-id", "origin-json"):
        reuse_result.add_argument("--" + flag, required=True)
    reuse_result.add_argument(
        "--role", choices=["source", "support", "journal"], required=True
    )

    prepare_workflow = subparsers.add_parser("prepare-workflow")
    prepare_workflow.add_argument("--engagement-id", required=True)
    prepare_workflow.add_argument(
        "--workflow-id",
        choices=list(
            CLIENT_WORKFLOW_IDS
            if os.environ.get("LUCIA_ASSURANCE_HOST") == "1"
            else VERA_CLIENT_WORKFLOW_IDS
        ),
        required=True,
    )

    check_entries_handoff = subparsers.add_parser("start-check-entries-from-sample")
    check_entries_handoff.add_argument("--client-id", required=True)
    check_entries_handoff.add_argument("--engagement-id", required=True)
    check_entries_handoff.add_argument("--sample-run-id", required=True)
    check_entries_handoff.add_argument("--source-engagement-id")
    check_entries_handoff.add_argument(
        "--support-input-id", action="append", default=[]
    )
    check_entries_handoff.add_argument("--label")
    check_entries_handoff.add_argument("--purpose")
    check_entries_handoff.add_argument("--idempotency-key")
    check_entries_handoff.add_argument("--new-run", action="store_true")
    prepare_workflow.add_argument("--input-id", action="append", default=[])
    prepare_workflow.add_argument(
        "--upstream-artifact",
        action="append",
        default=[],
        help="Exact upstream reference formatted run_id:artifact_id:role.",
    )
    prepare_workflow.add_argument(
        "--continue-from-run",
        help="Prepare a new technical run from the selected run’s verified sources",
    )
    prepare_workflow.add_argument("--label")
    prepare_workflow.add_argument("--purpose")
    prepare_workflow.add_argument(
        "--idempotency-key",
        help="Stable request key; use a different key for each intentionally separate run.",
    )
    prepare_workflow.add_argument(
        "--new-run",
        action="store_true",
        help="Create the explicit-new namespace; retries with the same key remain idempotent.",
    )

    for command in (
        "start-workflow",
        "cancel-workflow",
        "complete-workflow",
        "verify-run-report",
        "checkpoint-workflow",
        "restore-workflow",
    ):
        lifecycle = subparsers.add_parser(command)
        lifecycle.add_argument("--client-id", required=True)
        lifecycle.add_argument("--engagement-id", required=True)
        lifecycle.add_argument("--run-id", required=True)
        if command == "restore-workflow":
            lifecycle.add_argument("--destination", required=True)

    write_artifact = subparsers.add_parser("write-run-artifact")
    write_artifact.add_argument("--client-id", required=True)
    write_artifact.add_argument("--engagement-id", required=True)
    write_artifact.add_argument("--run-id", required=True)
    write_artifact.add_argument("--name", required=True)
    artifact_content = write_artifact.add_mutually_exclusive_group(required=True)
    artifact_content.add_argument("--content")
    artifact_content.add_argument("--content-stdin", action="store_true")

    read_artifact = subparsers.add_parser("read-run-artifact")
    read_artifact.add_argument("--client-id", required=True)
    read_artifact.add_argument("--engagement-id", required=True)
    read_artifact.add_argument("--run-id", required=True)
    read_artifact.add_argument("--path", required=True)
    read_artifact.add_argument("--offset", type=int, default=0)
    read_artifact.add_argument("--limit", type=int)
    read_artifact.add_argument("--column", type=int, action="append")

    fail_workflow = subparsers.add_parser("fail-workflow")
    fail_workflow.add_argument("--client-id", required=True)
    fail_workflow.add_argument("--engagement-id", required=True)
    fail_workflow.add_argument("--run-id", required=True)
    fail_workflow.add_argument("--reason", required=True)

    finalize_workflow = subparsers.add_parser("finalize-workflow")
    finalize_workflow.add_argument("--client-id", required=True)
    finalize_workflow.add_argument("--engagement-id", required=True)
    finalize_workflow.add_argument("--run-id", required=True)
    artifact_source = finalize_workflow.add_mutually_exclusive_group()
    artifact_source.add_argument(
        "--artifacts-json",
        help="Omit to list this run’s physical output paths before declaring them.",
    )
    artifact_source.add_argument(
        "--artifacts-stdin",
        action="store_true",
        help="Read artifact declarations from standard input without command-line size limits.",
    )
    finalize_workflow.add_argument("--expected-declaration-sha256")

    close_engagement = subparsers.add_parser("close-engagement")
    close_engagement.add_argument("--client-id", required=True)
    close_engagement.add_argument("--engagement-id", required=True)

    subparsers.add_parser("recover-ledger")

    retention = subparsers.add_parser("retention-report")
    retention.add_argument("--client-id", required=True)
    retention.add_argument("--older-than-days", type=int)

    configure_client = subparsers.add_parser("configure-client")
    configure_client.add_argument("--general-workspace", action="store_true")
    configure_client.add_argument("--scope-id", required=True)
    configure_client.add_argument("--email-address", action="append", default=[])
    configure_client.add_argument("--legal-name", action="append", default=[])
    configure_client.add_argument("--tax-identifier", action="append", default=[])
    configure_client.add_argument("--replace-orphaned-scope-id")

    refresh = subparsers.add_parser("refresh")
    refresh.add_argument("--rebuild", action="store_true")
    refresh.add_argument("--enable-ocr", action="store_true")
    refresh.add_argument(
        "--ocr-language", choices=("it", "fr", "de", "en", "es"), default="it"
    )

    search = subparsers.add_parser("search")
    search.add_argument("--query", required=True)
    search.add_argument("--scope-id", required=True)
    search.add_argument("--limit", type=int, default=10)

    open_source = subparsers.add_parser("open")
    open_source.add_argument("--source-id", required=True)
    open_source.add_argument("--context-chunks", type=int, default=0)

    plan_gmail = subparsers.add_parser("plan-gmail")
    plan_gmail.add_argument("--scope-id", required=True)
    plan_gmail.add_argument("--topic")
    plan_gmail.add_argument("--after")
    plan_gmail.add_argument("--before")

    match_email = subparsers.add_parser("match-email")
    match_email.add_argument("--header-address", action="append", required=True)
    match_email.add_argument("--headers-complete", action="store_true")
    match_email.add_argument("--expected-scope-id")
    return parser


def main(argv: list[str] | None = None) -> int:
    """Execute one Studio Archive operation and emit structured JSON."""

    args = _parser().parse_args(argv)
    with ExitStack() as stack:
        return _execute(args, stack)


def _execute(args: argparse.Namespace, stack: ExitStack) -> int:
    try:
        stack.enter_context(use_studio_run_context(args.context))
        if args.command == "record-error":
            envelope = json.load(sys.stdin)
            result = {
                "recorded": record_error(
                    envelope["arguments"], envelope["payload"], channel="mcp"
                )
            }
        elif args.command == "setup":
            result = setup_archive_with_folder_picker()
        elif args.command == "configure":
            result = configure_archive(
                args.archive_root,
                host_access_approved=args.host_folder_access_approved,
                make_studio_default=args.make_studio_default,
            )
        elif args.command == "diagnose-access":
            result = diagnose_archive_access(
                args.archive_root,
                host_access_approved=args.host_folder_access_approved,
            )
        elif args.command == "status":
            result = studio_archive_status()
        elif args.command == "normalize-project-layout":
            result = normalize_studio_archive_layout()
        elif args.command == "clients":
            result = list_studio_clients()
        elif args.command == "resolve-client":
            result = resolve_studio_client_identity(
                args.identity_kind,
                args.identity_value,
            )
        elif args.command == "client-folder":
            result = get_studio_client_folder(args.client_id)
        elif args.command == "check-import-sources":
            result = check_studio_import_sources(
                args.source_path, expected_sha256=args.expected_sha256
            )
        elif args.command == "create-client":
            result = create_studio_client(
                args.legal_name,
                general_workspace=args.general_workspace,
                email_addresses=args.email_address,
                tax_identifiers=args.tax_identifier,
            )
        elif args.command == "create-engagement":
            result = create_studio_client_engagement(
                args.client_id,
                args.engagement_label,
                idempotency_key=args.idempotency_key,
            )
        elif args.command == "copy-client-source-folder":
            result = copy_studio_client_source_folder(
                args.client_id,
                args.engagement_id,
                args.source_path,
                copy_authorized=args.copy_authorized,
                destination_name=args.destination_name,
            )
        elif args.command == "import-document":
            result = import_studio_client_document(
                args.client_id,
                args.source_path,
                args.role,
                engagement_id=args.engagement_id,
                expected_sha256=args.expected_sha256,
            )
        elif args.command == "engagements":
            result = list_studio_client_engagements(args.client_id)
        elif args.command == "verify-inputs":
            result = verify_studio_client_inputs(
                args.client_id,
                args.engagement_id,
                args.input_id,
                expected_receipts=(
                    json.loads(args.expected_receipts_json)
                    if args.expected_receipts_json is not None
                    else None
                ),
                require_exact_input_set=args.require_exact_input_set,
            )
        elif args.command == "snapshot-client-folder":
            result = snapshot_studio_client_folder(
                args.client_id,
                args.engagement_id,
            )
        elif args.command == "authorize-google-drive":
            result = authorize_studio_google_drive(args.client_secrets)
        elif args.command == "google-drive-status":
            result = studio_google_drive_status()
        elif args.command == "bind-google-drive":
            result = bind_studio_client_google_drive(
                args.client_id,
                args.folder_id,
            )
        elif args.command == "snapshot-google-drive":
            result = snapshot_studio_client_google_drive(
                args.client_id,
                args.engagement_id,
            )
        elif args.command == "archive-organization-inventory":
            result = get_studio_archive_organization_inventory(
                args.client_id,
                args.engagement_id,
                args.snapshot_input_id,
            )
        elif args.command == "open-archive-organization-item":
            result = open_studio_archive_organization_item(
                args.client_id,
                args.engagement_id,
                args.snapshot_input_id,
                args.item_ref,
            )
        elif args.command == "map-legacy-incarichi":
            result = map_studio_legacy_incarichi(
                args.client_id, args.engagement_id, json.loads(args.targets_json)
            )
        elif args.command == "open-incarico-document":
            result = read_studio_incarico_document(
                args.client_id, args.engagement_id, json.loads(args.reference_json)
            )
        elif args.command == "begin-incarico":
            result = begin_studio_incarico(
                args.client_id,
                args.engagement_id,
                args.workflow_id,
                args.purpose,
                originating_conversation=(
                    json.loads(args.originating_conversation_json)
                    if args.originating_conversation_json
                    else None
                ),
            )
        elif args.command == "publish-incarico-result":
            result = publish_studio_incarico_result(
                args.client_id,
                args.engagement_id,
                args.entry_key,
                args.label,
                json.loads(args.files_json),
                args.expected_revision,
                args.idempotency_key,
                primary_format=args.primary_format,
            )
        elif args.command == "reuse-incarico-result":
            result = reuse_studio_incarico_result(
                args.client_id,
                args.engagement_id,
                json.loads(args.origin_json),
                args.role,
            )
        elif args.command == "incarico":
            if args.fields_json is None:
                result = get_studio_incarico(args.client_id, args.engagement_id)
            else:
                fields = json.loads(args.fields_json)
                if not isinstance(fields, dict):
                    raise ArchiveError("Assignment fields must be an object")
                result = update_studio_incarico(
                    args.client_id, args.engagement_id, fields, args.expected_revision
                )
        elif args.command == "prepare-workflow":
            upstream_artifacts = []
            for raw_reference in args.upstream_artifact:
                parts = raw_reference.split(":", maxsplit=2)
                if len(parts) != 3:
                    raise ArchiveError(
                        "Upstream artifact must be run_id:artifact_id:role."
                    )
                origin = parts[0].split("/", maxsplit=1)
                upstream_artifacts.append(
                    {
                        **({"engagement_id": origin[0]} if len(origin) == 2 else {}),
                        "run_id": origin[-1],
                        "artifact_id": parts[1],
                        "role": parts[2],
                    }
                )
            result = prepare_studio_client_workflow(
                args.engagement_id,
                args.workflow_id,
                input_ids=args.input_id,
                continue_from_run=args.continue_from_run,
                upstream_artifacts=upstream_artifacts,
                label=args.label,
                purpose=args.purpose,
                idempotency_key=args.idempotency_key,
                new_run=args.new_run,
            )
        elif args.command == "verify-run-report":
            result = verify_studio_run_report(
                args.client_id, args.engagement_id, args.run_id
            )
        elif args.command == "write-run-artifact":
            content = sys.stdin.read(65537) if args.content_stdin else args.content
            result = write_studio_run_artifact(
                args.client_id, args.engagement_id, args.run_id, args.name, content
            )
        elif args.command == "read-run-artifact":
            result = read_studio_run_artifact(
                args.client_id,
                args.engagement_id,
                args.run_id,
                args.path,
                offset=args.offset,
                limit=args.limit,
                columns=args.column,
            )
        elif args.command == "start-workflow":
            result = start_studio_client_workflow(
                args.client_id, args.engagement_id, args.run_id
            )
        elif args.command == "checkpoint-workflow":
            result = checkpoint_studio_client_workflow(
                args.client_id, args.engagement_id, args.run_id
            )
        elif args.command == "restore-workflow":
            result = restore_studio_client_workflow(
                args.client_id, args.engagement_id, args.run_id, args.destination
            )
        elif args.command == "start-check-entries-from-sample":
            result = start_check_entries_from_sample(
                args.client_id,
                args.engagement_id,
                args.sample_run_id,
                support_input_ids=args.support_input_id,
                source_engagement_id=args.source_engagement_id,
                label=args.label,
                purpose=args.purpose,
                idempotency_key=args.idempotency_key,
                new_run=args.new_run,
            )
        elif args.command == "fail-workflow":
            result = fail_studio_client_workflow(
                args.client_id, args.engagement_id, args.run_id, args.reason
            )
        elif args.command == "cancel-workflow":
            result = cancel_studio_client_workflow(
                args.client_id, args.engagement_id, args.run_id
            )
        elif args.command == "finalize-workflow":
            artifact_payload = None
            if args.artifacts_json is not None:
                artifact_payload = json.loads(args.artifacts_json)
            elif args.artifacts_stdin:
                artifact_payload = json.load(sys.stdin)
            if (
                args.artifacts_json is not None or args.artifacts_stdin
            ) and not isinstance(artifact_payload, list):
                raise ArchiveError("Artifact declarations must contain a JSON array.")
            result = finalize_studio_client_workflow(
                args.client_id,
                args.engagement_id,
                args.run_id,
                artifact_payload,
                expected_declaration_sha256=args.expected_declaration_sha256,
            )
        elif args.command == "complete-workflow":
            result = complete_studio_client_workflow(
                args.client_id, args.engagement_id, args.run_id
            )
        elif args.command == "close-engagement":
            result = close_studio_client_engagement(args.client_id, args.engagement_id)
        elif args.command == "recover-ledger":
            result = recover_studio_client_ledger()
        elif args.command == "retention-report":
            result = report_studio_client_retention(
                args.client_id, older_than_days=args.older_than_days
            )
        elif args.command == "configure-client":
            result = set_studio_client_identity(
                args.scope_id,
                general_workspace=args.general_workspace,
                email_addresses=args.email_address,
                legal_names=args.legal_name,
                tax_identifiers=args.tax_identifier,
                replace_orphaned_scope_id=args.replace_orphaned_scope_id,
            )
        elif args.command == "refresh":
            result = refresh_archive(
                rebuild=args.rebuild,
                enable_ocr=args.enable_ocr,
                ocr_language=args.ocr_language,
            )
        elif args.command == "search":
            result = search_archive(
                args.query,
                scope_id=args.scope_id,
                limit=args.limit,
            )
        elif args.command == "open":
            result = open_archive_source(
                args.source_id,
                context_chunks=args.context_chunks,
            )
        elif args.command == "plan-gmail":
            result = plan_gmail_client_search(
                args.scope_id,
                topic=args.topic,
                after=args.after,
                before=args.before,
            )
        else:
            result = match_studio_email_client(
                args.header_address,
                headers_complete=args.headers_complete,
                expected_scope_id=args.expected_scope_id,
            )
    except (ArchiveError, OSError, ValueError, sqlite3.Error) as exc:
        # Keep the exception alive for the source-bound collector and retain
        # its traceback locally; the JSON response remains the caller's result.
        logging.exception("Studio Archive operation failed")
        error = {
            "code": getattr(exc, "code", "archive_operation_failed"),
            "message": str(exc),
        }
        details = getattr(exc, "details", None)
        if isinstance(details, dict):
            error["details"] = details
        payload = {"error": error}
        if (
            args.command != "record-error"
            and os.environ.get("VERA_STUDIO_ARCHIVE_MCP") != "1"
        ):
            try:
                record_error(vars(args), payload, channel="cli")
            except (OSError, ValueError, sqlite3.Error):
                logging.exception("Studio Archive error recording failed")
                payload["reporting"] = {
                    "status": "unavailable",
                    "code": "archive_reporting_failed",
                    "measurement_gap": True,
                    "retry_action": "retry_reporting_only",
                }
        _emit(payload)
        return 1
    _emit(result)
    return (
        1 if args.command == "verify-inputs" and result["verified"] is not True else 0
    )


if __name__ == "__main__":
    raise SystemExit(main())

SHA-256: f2a416c1426d34b9dc47740d006e86186fb94eee1da045aff8a7dbfaca87c63a