vidbyte-cli 0.1.0__py3-none-any.whl

vidbyte_cli/lib/errors/failures.py

@@ -0,0 +1,2910 @@
+"""One CliError subclass per failure the platform can raise, prose included.
+
+This is where the agent-native `description` and `trace` text lives. Keeping it here rather
+than at the raise site means a caller writes `raise EmptyPrompt()` in one line, two commands
+that fail the same way cannot drift apart, and the wording is reviewable in one place.
+
+Nothing in this file may embed a secret: `description` and `trace` are static authored text
+and must stay independent of credentials, prompt bodies, and backend response content.
+"""
+
+from __future__ import annotations
+
+from pydantic import JsonValue
+
+from .cli_error import CliError
+from .codes import CliErrorCode, ExitCode
+
+
+class PersistenceHostFailed(CliError):
+    """The local Codex process did not complete a valid turn."""
+
+    code = CliErrorCode.OPERATION_FAILED
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+
+    def __init__(self) -> None:
+        # Host diagnostics can contain secrets or task text, so this message is static.
+        super().__init__(
+            "Codex did not complete the persistence turn.",
+            description=(
+                "Codex failed, timed out, or returned an incomplete or mismatched conversation. "
+                "Continuation stopped immediately. The admission may already have been charged "
+                "and completed local work remains in the working directory."
+            ),
+            trace="PersistentCodexSession checked the SDK turn status and conversation identity.",
+            hint="Inspect local Codex session history and configuration before retrying.",
+        )
+
+
+class TaskBoardHostFailed(CliError):
+    """The local Codex process did not complete a valid board task turn."""
+
+    code = CliErrorCode.OPERATION_FAILED
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+
+    def __init__(self) -> None:
+        # Host diagnostics can contain secrets or task text, so this message is static.
+        super().__init__(
+            "Codex did not complete the task-board turn.",
+            description=(
+                "Codex failed, timed out, or returned an incomplete board task turn. "
+                "The board stopped or marked the task failed per its stop-on-error policy. "
+                "The admission may already have been charged and completed local work remains."
+            ),
+            trace="TaskBoardCodexSession checked the SDK turn status and thread identity.",
+            hint="Inspect local Codex session history and configuration before retrying.",
+        )
+
+
+class TaskBoardInputInvalid(CliError):
+    """The board was given neither exactly one task source nor a usable one."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(self) -> None:
+        # Reports only the accepted shapes, never the submitted task text or file contents.
+        super().__init__(
+            "Supply either literal task arguments or one or more --task-file paths, not both.",
+            description=(
+                "A task board is built from exactly one kind of source: literal task strings "
+                "passed as arguments, or Markdown files where each whole file is one task. "
+                "Mixing the two, or supplying neither, leaves the board's order ambiguous, so "
+                "the invocation was rejected before credentials, payment, or host execution. "
+                "Re-run with only positional tasks, or only repeated --task-file paths."
+            ),
+            trace="TaskBoardCommand resolved the board source before building a launch plan.",
+            hint="Repeat --task-file once per task file; each file is one whole task.",
+        )
+
+
+class TaskBoardTaskFileInvalid(CliError):
+    """One supplied task file is not a readable, non-empty Markdown file."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(self) -> None:
+        # File contents are task text, so neither the path nor the body is echoed here.
+        super().__init__(
+            "Every --task-file must be a readable, non-empty .md file.",
+            description=(
+                "A task file carries one whole task, so it has to be a Markdown file with "
+                "content: a non-.md suffix, an unreadable file, or a file that is empty after "
+                "trimming cannot become a board entry. The board was rejected before "
+                "credentials, payment, or host execution, and no file path or body is repeated "
+                "in this error. Check the suffix and contents of each --task-file and retry."
+            ),
+            trace="TaskBoardCommand read each task file while resolving the board source.",
+            hint="One task per .md file; use positional arguments for short literal tasks.",
+        )
+
+
+class TaskBoardCheckpointMissing(CliError):
+    """A resume asked for steps whose checkpoint files are absent from disk."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(self, index: int) -> None:
+        # Names only the step number; task text and directory layout stay out of prose.
+        super().__init__(
+            f"No checkpoint exists for board step {index}.",
+            description=(
+                "Resuming reuses stored steps instead of re-running them, so every step "
+                f"before the resume point must exist on disk and step {index} has no file. "
+                "The board ran nothing: no admission was bought and no agent started. "
+                "Resume from an earlier step, or run the board fresh without --from."
+            ),
+            trace="TaskBoardCheckpointer.load_prefix read the step files in order.",
+            hint="Check .vidbyte/task-board for the board directory matching this run.",
+        )
+
+
+class TaskBoardCheckpointMismatch(CliError):
+    """Stored checkpoints do not match the board or settings of this invocation."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(self, detail: str) -> None:
+        # Carries only a fixed mismatch category, never task text or file bodies.
+        super().__init__(
+            "Stored checkpoints do not match this board invocation.",
+            description=(
+                "A resume or replay replays stored prompts exactly, so the task list and "
+                f"the window, context, and summary settings must match the stored run: {detail} "
+                "differs. The board ran nothing: no admission was bought and no agent "
+                "started. Re-run with the original board and settings, or start fresh."
+            ),
+            trace="TaskBoardCheckpointer.validate_manifest compared the stored manifest.",
+            hint="Use --checkpoint-id to resume a different stored board explicitly.",
+        )
+
+
+class TaskBoardBoardNotFound(CliError):
+    """No checkpointed board with the requested id exists under the checkpoint root."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(self, board_id: str) -> None:
+        # Names only the requested id; the stored task text never enters an error message.
+        super().__init__(
+            f"No checkpointed board {board_id} exists under this checkpoint root.",
+            description=(
+                "Reading a board loads its board.json manifest from the directory named by "
+                f"the board id, and no readable manifest was found for {board_id}. Nothing "
+                "was read, written, or charged. List the boards under this root first, or "
+                "pass --checkpoint-root if the board was saved somewhere other than the "
+                "default directory."
+            ),
+            trace="TaskBoardCheckpointer.read_manifest resolved the board directory.",
+            hint="Run `runtime task-board list` to see every stored board and its path.",
+        )
+
+
+class TaskBoardTaskListInvalid(CliError):
+    """A board task-list file is missing, unreadable, or not a supported board format."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(self) -> None:
+        # File contents are task text, so neither the path nor the body is echoed here.
+        super().__init__(
+            "A board task list must be a readable .md file of level-two sections or a "
+            ".json array of task strings.",
+            description=(
+                "A task list carries a whole board in one reviewable file, so it has to be "
+                "one of exactly two shapes: Markdown whose level-two headings separate the "
+                "tasks, or JSON holding a flat array of non-empty strings. The file was "
+                "unreadable, had an unsupported suffix, held a different JSON shape, or "
+                "produced no tasks at all. No board was built and nothing was charged."
+            ),
+            trace="TaskBoardTaskFiles.read_task_list parsed the supplied board file.",
+            hint="Export an existing board with `runtime task-board export-tasks` to see "
+            "the expected shape.",
+        )
+
+
+class TaskBoardBoardIdInvalid(CliError):
+    """A board id is not a single safe directory name inside the checkpoint root."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(self, option: str) -> None:
+        # Names the option, never the rejected value, which may be an arbitrary path.
+        super().__init__(
+            f"{option} must be 1 to 64 letters, digits, dots, underscores, or hyphens, and "
+            "not only dots.",
+            description=(
+                "A board id names exactly one directory directly inside the checkpoint root, "
+                "so it may not contain a path separator or be made only of dots, which would "
+                f"address a directory outside that root. The value given for {option} broke "
+                "that rule, so nothing was read, written, or charged. Copy the id from a run "
+                "result or from `runtime task-board list` instead of passing a path."
+            ),
+            trace="TaskBoardCommand checked the board id before building any board directory.",
+            hint="Pass the directory to --checkpoint-root and only the board's name as the id.",
+        )
+
+
+class TaskBoardCheckpointRootUnreadable(CliError):
+    """The checkpoint root cannot be resolved or scanned for boards."""
+
+    code = CliErrorCode.OPERATION_FAILED
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+
+    def __init__(self, reason: str) -> None:
+        # The caller passed the root themselves, so the option name is enough to act on.
+        super().__init__(
+            f"The checkpoint root could not be read: {reason}.",
+            description=(
+                "Every board lives in a subdirectory of the checkpoint root, so a root that "
+                f"cannot be resolved or listed hides every board inside it; here {reason}. "
+                "Nothing was read, written, or charged. Retrying unchanged fails the same way; "
+                "fix the directory's permissions or pass a different --checkpoint-root."
+            ),
+            trace="TaskBoardCommand resolved --checkpoint-root and scanned it for boards.",
+            hint="Pass --checkpoint-root pointing at the readable directory holding your boards.",
+        )
+
+
+class TaskBoardManifestUnreadable(CliError):
+    """A board directory holds a board.json manifest that cannot be used."""
+
+    code = CliErrorCode.OPERATION_FAILED
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+
+    def __init__(self, board_id: str, reason: str) -> None:
+        # Names the board and a fixed reason category; the manifest body is task text.
+        super().__init__(
+            f"Board {board_id} has an unusable board.json manifest: {reason}.",
+            description=(
+                "The manifest is what makes a board addressable by id: it records the task "
+                f"list and the settings every stored prompt depends on, and here {reason}. "
+                "Nothing was changed and nothing was charged, and the step files beside it "
+                "are untouched. Fix the file's permissions if that is the reason; a corrupt "
+                "or pre-version-2 manifest cannot be resumed, so start a fresh board instead."
+            ),
+            trace="TaskBoardCheckpointer.read_manifest loaded board.json from the board directory.",
+            hint="Fix board.json permissions, or rerun the board under a new --checkpoint-id.",
+        )
+
+
+class TaskBoardStepUnreadable(CliError):
+    """A stored step file exists but cannot be read or does not hold a valid step record."""
+
+    code = CliErrorCode.OPERATION_FAILED
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+
+    def __init__(self, board_id: str, index: int, reason: str) -> None:
+        # Names the board, the step number, and a fixed reason; never the stored prompt.
+        super().__init__(
+            f"Board {board_id} step {index} is stored but unreadable: {reason}.",
+            description=(
+                f"step-{index}.json exists in the board directory, but {reason}, so it can "
+                "neither be reported nor reused as context for later steps. Nothing was "
+                "changed or charged. Fix the file's permissions if that is the reason; "
+                "otherwise re-run just that step with `runtime task-board run "
+                f"--checkpoint-id {board_id} --replay-task {index}`, which rewrites the file "
+                "and buys one admission."
+            ),
+            trace="TaskBoardCheckpointer.read_step read and validated one step file.",
+            hint=f"Replay step {index} to rebuild its checkpoint file.",
+        )
+
+
+class TaskBoardStepNotStored(CliError):
+    """show-step asked for a step index that has no checkpoint file on this board."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(self, board_id: str, index: int, task_count: int) -> None:
+        # Tells an out-of-range index apart from a step that simply has not run yet.
+        where = (
+            f"the board only has {task_count} tasks, so valid indices are 0 to {task_count - 1}"
+            if index >= task_count
+            else "that step has not run yet, or its file was removed"
+        )
+        super().__init__(
+            f"Board {board_id} has no stored step {index}.",
+            description=(
+                f"show-step reads step-{index}.json from the board directory and that file "
+                f"does not exist: {where}. Nothing was read, written, or charged. Run "
+                "`runtime task-board status` to see the completed and failed indices that do "
+                "have stored records, and pass one of those to --index."
+            ),
+            trace="TaskBoardCommand.execute_show_step read one step file from the board.",
+            hint="Run `runtime task-board status --checkpoint-id` first to list stored indices.",
+        )
+
+
+class TaskBoardForkTargetExists(CliError):
+    """fork was asked to write into a board id that already has a directory."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(self, into: str) -> None:
+        # Refusing is the whole point: a fork over a board would destroy that board's history.
+        super().__init__(
+            f"Board {into} already exists under this checkpoint root.",
+            description=(
+                "A fork writes a copied prefix and a new manifest into its own directory, and "
+                f"a directory named {into} is already there. Writing over it would destroy "
+                "whatever history it holds, so nothing was copied, written, or charged. Pick "
+                "an unused --into id, or remove that directory yourself if it is a leftover."
+            ),
+            trace="TaskBoardCommand.execute_fork checked the target directory before copying.",
+            hint="Run `runtime task-board list` to see which board ids are already taken.",
+        )
+
+
+class TaskBoardForkPrefixIncomplete(CliError):
+    """fork --at asks for more leading steps than the source board has stored."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(
+        self, board_id: str, at_index: int, available: int, task_count: int, missing: int
+    ) -> None:
+        # `available` is the length of the unbroken stored prefix, i.e. the largest valid --at;
+        # `missing` is the board index of the first absent step, which differs on a DAG board.
+        where = (
+            f"the board only has {task_count} tasks"
+            if at_index > task_count
+            else f"step {missing} has no stored checkpoint"
+        )
+        super().__init__(
+            f"Board {board_id} cannot be forked at {at_index}: {where}.",
+            description=(
+                "A fork copies the first --at steps in the order the board runs them, which is "
+                "board order unless the board is a DAG, and every one of them must "
+                f"already be stored, but {where}. Nothing was copied, written, or charged, so "
+                "no partial board was created. The largest --at this board supports right "
+                f"now is {available}; fork there, or finish the board first."
+            ),
+            trace="TaskBoardCheckpointer.fork_into checked the stored prefix before copying.",
+            hint=f"Retry with --at {available} or lower.",
+        )
+
+
+class TaskBoardForkFailed(CliError):
+    """Copying a fork's prefix or writing its manifest failed on the filesystem."""
+
+    code = CliErrorCode.OPERATION_FAILED
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+
+    def __init__(self, into: str, reason: str) -> None:
+        # The manifest is written last, so a failure leaves a directory no verb treats as a board.
+        super().__init__(
+            f"Forking into board {into} failed: {reason}.",
+            description=(
+                f"The copy stopped partway because {reason}. The source board is untouched, "
+                f"but the {into} directory may now hold copied step files with no manifest, "
+                "which list ignores and which blocks reusing that id. Nothing was charged. "
+                f"Fix the cause, delete the {into} directory, and run the same fork again."
+            ),
+            trace="TaskBoardCheckpointer.fork_into copied step files, then wrote the manifest.",
+            hint=f"Delete the partial {into} directory before retrying the same --into.",
+        )
+
+
+class TaskBoardOutputWriteFailed(CliError):
+    """A file a task-board verb was asked to write could not be written."""
+
+    code = CliErrorCode.OPERATION_FAILED
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+
+    def __init__(self, option: str, reason: str) -> None:
+        # Names the option that chose the destination, since that is what the caller changes.
+        super().__init__(
+            f"The file named by {option} could not be written: {reason}.",
+            description=(
+                f"The board itself was read successfully, but writing the {option} "
+                f"destination failed because {reason}. The write goes through a temporary "
+                "sibling, so any previous file at that path is intact. Nothing was charged; "
+                f"pass a {option} path inside a writable directory and run the command again."
+            ),
+            trace="TaskBoardCommand rendered the output and handed it to LocalFileStore.",
+            hint=f"Choose a {option} path in a directory you can write to.",
+        )
+
+
+class TaskBoardExportDestinationInvalid(CliError):
+    """export-tasks was given a destination whose suffix names no supported format."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(self) -> None:
+        # The suffix picks the format, so an unknown suffix has no well-defined output.
+        super().__init__(
+            "The export-tasks destination must end in .md, .markdown, or .json.",
+            description=(
+                "The destination's suffix chooses the format: Markdown gets one level-two "
+                "section per task and JSON gets a flat array of task strings, and both reload "
+                "through --task-list. Any other suffix names a format this command cannot "
+                "write, so nothing was written and nothing was charged. Rename the --to path."
+            ),
+            trace="TaskBoardTaskFiles.write_task_list chose a format from the suffix.",
+            hint="Use --to board.md or --to board.json.",
+        )
+
+
+class TaskBoardDependencyInvalid(CliError):
+    """One supplied dependency link is malformed or the link set is not a DAG."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(self) -> None:
+        # Reports only the accepted grammar, never the submitted indices or task text.
+        super().__init__(
+            "Dependency links must be CHILD:PARENT pairs forming an acyclic graph.",
+            description=(
+                "A link names 0-based board positions as CHILD:PARENT with comma-separated "
+                "parents, so --depends-on 8:2 means task 8 reads task 2 and runs after it. "
+                "Links need --type dag, must stay inside the board, allow no self-links, "
+                "duplicates, or cycles, and are rejected before credentials, payment, or "
+                "host execution. The board order and task text are never repeated here."
+            ),
+            trace="TaskBoardCommand parsed dependency links before building a launch plan.",
+            hint="Repeat --depends-on once per link, e.g. --type dag --depends-on 8:2.",
+        )
+
+
+class TaskBoardDecomposeInvalid(CliError):
+    """Decomposition was combined with a feature that requires stable board indices."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(self, conflict: str) -> None:
+        # Names the conflicting option without repeating task text or other local input.
+        super().__init__(
+            f"--allow-decompose cannot be combined with {conflict}.",
+            description=(
+                "Decomposition replaces one task with subtasks at the same index, so every "
+                "later task shifts while the board runs. Checkpoints store steps by board "
+                "index and DAG links name board indices, so neither can describe a board that "
+                f"reshapes itself, and {conflict} was requested. The flags were rejected before "
+                "credentials, payment, or host execution, so nothing was charged. Checkpointing "
+                "is on by default, so a plain --allow-decompose run hits this until "
+                "--no-checkpoint is added as well. A decomposing board therefore runs as linear "
+                "and unchecked: it cannot be resumed, repaired, replayed, or forked afterwards, "
+                "so keep --allow-decompose off for any board you may need to continue later."
+            ),
+            trace="TaskBoardCommand validated decompose flags before building a launch plan.",
+            hint="Re-run with --allow-decompose --no-checkpoint and without --type dag.",
+        )
+
+
+class InvalidCommandUsage(CliError):
+    """Click rejected the invocation before any command body ran."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(self, message: str, command_path: str, exit_code: int, cause: Exception) -> None:
+        super().__init__(
+            message,
+            description=(
+                "The command line did not match the declared command tree, so parsing stopped "
+                "before any command ran. The wording comes from Click and names only parser "
+                "values, never user data. No backend request was made and no local state "
+                "changed. Correct the invocation and run it again."
+            ),
+            trace=(
+                "CliApplication.run built the command tree and delegated to Click, which "
+                "rejected the arguments while resolving the command and its parameters."
+            ),
+            exit_code=exit_code,
+            hint=f"Run '{command_path} --help' for usage.",
+            cause=cause,
+        )
+
+
+class ConflictingOutputFormat(CliError):
+    """`--json` was combined with an incompatible `--format` value."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(self) -> None:
+        super().__init__(
+            "--json conflicts with the selected --format value.",
+            description=(
+                "`--json` is exactly an alias for `--format json`, so pairing it with any other "
+                "format asks for two different result encodings on one stream. The CLI refuses "
+                "rather than silently picking a winner, because a machine consumer cannot "
+                "detect the substitution. Pass one of the two flags."
+            ),
+            trace=(
+                "CliApplication.run resolved root output policy through "
+                "RootOptionInspector/_resolve_output_format before constructing any service."
+            ),
+            hint="Remove --json or use --format json.",
+        )
+
+
+class OperationInterrupted(CliError):
+    """The invocation was cancelled by the user or an abort."""
+
+    code = CliErrorCode.INTERRUPTED
+    exit_status = ExitCode.INTERRUPTED
+
+    def __init__(self) -> None:
+        super().__init__(
+            "Operation interrupted.",
+            description=(
+                "Ctrl-C or a Click abort ended the invocation before it completed. Work already "
+                "submitted to the Vidbyte backend is not cancelled by this signal and may still "
+                "be running. Status 130 is the conventional shell code for an interrupt, so a "
+                "caller can tell cancellation apart from failure."
+            ),
+            trace=(
+                "The interrupt reached the CliApplication.run boundary from wherever the "
+                "invocation was waiting — argument parsing, prompting, or command execution."
+            ),
+        )
+
+
+class UnexpectedInternalError(CliError):
+    """An unclassified exception reached the application boundary."""
+
+    code = CliErrorCode.INTERNAL_ERROR
+    exit_status = ExitCode.SOFTWARE
+
+    def __init__(self, cause: Exception | None) -> None:
+        super().__init__(
+            "An unexpected internal error occurred.",
+            description=(
+                "An exception escaped without being classified by the code that raised it, so "
+                "this is a CLI defect rather than an invocation mistake. The original exception "
+                "value is withheld because it may quote a credential, a prompt, or a backend "
+                "response body. The command's effect is unknown; verify state before retrying."
+            ),
+            trace=(
+                "ErrorHandler.handle received an exception that matched neither CliError, nor a "
+                "Click exception, nor an interrupt, at the CliApplication.run boundary."
+            ),
+            hint="Retry with --debug for a redacted stack trace.",
+            cause=cause,
+        )
+
+
+class AuthenticationRequired(CliError):
+    """A command needing the Vidbyte API reached a machine with no stored credential."""
+
+    code = CliErrorCode.AUTH_REQUIRED
+    exit_status = ExitCode.AUTHENTICATION
+
+    def __init__(self) -> None:
+        super().__init__(
+            "Authentication is required.",
+            description=(
+                "The command needs a Vidbyte API key and the credential store held none for "
+                "this machine. Authentication is checked before repository inspection and "
+                "before any network call, so nothing was read or submitted. Log in once and "
+                "the key is reused by every later invocation."
+            ),
+            trace=(
+                "A command requiring the Vidbyte API — a research command through "
+                "ApplicationContext.api_client, or WhoamiCommand.execute directly — reached "
+                "CredentialResolver.resolve, which found no key in the environment, the "
+                "keyring, or the restricted file for this profile and host."
+            ),
+            hint="Run 'vidbyte-cli login' first.",
+        )
+
+
+class RuntimeHostUnavailable(CliError):
+    """The selected native coding-agent executable is absent from PATH."""
+
+    code = CliErrorCode.CONFIG_INVALID
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+
+    def __init__(self, host: str) -> None:
+        # Describes the missing executable without inspecting host configuration.
+        super().__init__(
+            f"No available local runtime host matched '{host}'.",
+            description=(
+                "The runtime requires an installed Codex, Claude Code, or OpenCode executable "
+                "and PATH discovery did not find the requested host. No host process started, "
+                "no Vidbyte request was sent, and no credits were spent. Install the host or "
+                "select one that runtime doctor reports as available."
+            ),
+            trace=(
+                "RuntimeLaunchPlanner asked RuntimeHostRegistry to resolve the requested "
+                "native host before paid admission."
+            ),
+            hint="Run 'vidbyte-cli runtime doctor' to inspect supported hosts.",
+        )
+
+
+class RuntimeWorkingDirectoryInvalid(CliError):
+    """The current path cannot be used as a native agent working directory."""
+
+    code = CliErrorCode.CONFIG_INVALID
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+
+    def __init__(self) -> None:
+        # Keeps the actual path out of failure prose because it may identify private projects.
+        super().__init__(
+            "The local runtime working directory is unavailable.",
+            description=(
+                "The current path did not resolve to a readable directory suitable for a native "
+                "agent process. The runtime stopped before authentication, payment, or process "
+                "creation, so no credits were spent and no local command ran. Change to the "
+                "intended project directory and retry."
+            ),
+            trace=(
+                "RuntimeLaunchPlanner validated the current working directory before "
+                "building a launch plan."
+            ),
+        )
+
+
+class RuntimeTaskInvalid(CliError):
+    """The local runtime task is blank or above its bounded input limit."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(self) -> None:
+        # Reports only the contract, never the submitted task text.
+        super().__init__(
+            "The runtime task must contain 1 to 20,000 characters.",
+            description=(
+                "The supplied task was blank after trimming or exceeded the local runtime's "
+                "bounded input contract. It was rejected before credentials, payment, or host "
+                "execution, and the task is not repeated in this error. Shorten the task or "
+                "supply non-whitespace instructions and retry."
+            ),
+            trace=(
+                "RuntimeLaunchPlanner validated task length before selecting a host or "
+                "building a plan."
+            ),
+        )
+
+
+class _AttachmentFailure(CliError):
+    """Shared safe envelope for explicit attachment validation failures."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(self, message: str, description: str, hint: str) -> None:
+        # Keeps attachment paths, bodies, and provider details out of public error fields.
+        super().__init__(
+            message,
+            description=description,
+            trace="AttachmentResolver validated explicit files before agent execution.",
+            hint=hint,
+        )
+
+
+class AttachmentInputInvalid(_AttachmentFailure):
+    """The programmatic attachment option value was not a tuple of paths."""
+
+    def __init__(self) -> None:
+        # Tells library callers to pass the same shape Click produces.
+        super().__init__(
+            "Attachment values must be a tuple of paths.",
+            "The attachment option received a value outside its typed programmatic contract, "
+            "so resolution stopped before filesystem access or agent execution. Pass zero or "
+            "more pathlib.Path values as the command parser does. No credentials, payment, "
+            "or model call was started.",
+            "Use the repeatable --attach PATH option or pass a tuple of Path values.",
+        )
+
+
+class AttachmentFileNotFound(_AttachmentFailure):
+    """An explicit attachment path does not exist."""
+
+    def __init__(self) -> None:
+        # Reports the repair without echoing a private path.
+        super().__init__(
+            "An attached file was not found.",
+            "One explicit attachment path did not resolve to an existing file, so the bundle "
+            "was rejected before any agent work began. The missing path is not repeated because "
+            "it may identify a private project. Check each --attach value and retry.",
+            "Check that every --attach path exists, then retry.",
+        )
+
+
+class AttachmentDirectory(_AttachmentFailure):
+    """An explicit attachment path identifies a directory."""
+
+    def __init__(self) -> None:
+        # Directories are rejected because attachment expansion is intentionally explicit.
+        super().__init__(
+            "Attached paths must identify files, not directories.",
+            "An explicit attachment path identified a directory, and the shared resolver never "
+            "scans or expands directories implicitly. Resolution stopped before credentials, "
+            "payment, or model execution. Supply each file explicitly and retry.",
+            "Replace directory paths with explicit file paths.",
+        )
+
+
+class AttachmentUnreadable(_AttachmentFailure):
+    """An explicit attachment could not be read."""
+
+    def __init__(self) -> None:
+        # Distinguishes filesystem access failure from unsupported file content.
+        super().__init__(
+            "An attached file could not be read.",
+            "The resolver could not read one explicit attachment because the path or its "
+            "permissions prevented access. The bundle was rejected before any agent work began, "
+            "and no file body is included in this error. Fix the local permissions or path and "
+            "retry.",
+            "Verify local read permissions for every --attach path.",
+        )
+
+
+class AttachmentUnsupported(_AttachmentFailure):
+    """An attachment is neither a supported image nor UTF-8 text."""
+
+    def __init__(self) -> None:
+        # Rejects binary data instead of silently turning it into corrupted prompt text.
+        super().__init__(
+            "The attached file type is unsupported.",
+            "The resolver accepts UTF-8 text and the native local-image formats only. One "
+            "attachment was neither, so the bundle was rejected before agent execution rather "
+            "than being decoded incorrectly. Convert the file to a supported form and retry.",
+            "Use a UTF-8 text file or a supported local image.",
+        )
+
+
+class AttachmentDuplicate(_AttachmentFailure):
+    """Two attachment arguments resolve to the same file."""
+
+    def __init__(self) -> None:
+        # Duplicate paths would make manifests and downstream context ambiguous.
+        super().__init__(
+            "The same file was attached more than once.",
+            "Two explicit attachment arguments resolved to one file, so the bundle was rejected "
+            "instead of silently changing its order or multiplying its context. No agent work "
+            "started. Remove the duplicate path and retry.",
+            "Pass each resolved file only once with --attach.",
+        )
+
+
+class AttachmentEmpty(_AttachmentFailure):
+    """An attachment contains no bytes."""
+
+    def __init__(self) -> None:
+        # Empty context cannot provide evidence and usually indicates a caller mistake.
+        super().__init__(
+            "Attached files must not be empty.",
+            "One explicit attachment contained zero bytes, so it could not provide usable task "
+            "context. Resolution stopped before credentials, payment, or model execution. Add "
+            "content or remove the empty path and retry.",
+            "Attach a non-empty file or omit the empty path.",
+        )
+
+
+class AttachmentTooLarge(_AttachmentFailure):
+    """One attachment exceeds the per-file byte boundary."""
+
+    def __init__(self) -> None:
+        # Enforces the per-file bound before decoding or provider work.
+        super().__init__(
+            "An attached file exceeds the per-file size limit.",
+            "One explicit attachment is larger than the shared per-file byte boundary, so the "
+            "resolver rejected it before decoding or agent execution. This protects prompt size "
+            "and keeps the input contract predictable. Split or reduce the file and retry.",
+            "Reduce the file below the per-file attachment limit and retry.",
+        )
+
+
+class AttachmentLimitExceeded(_AttachmentFailure):
+    """The attachment bundle exceeds its file-count or total-byte boundary."""
+
+    def __init__(self) -> None:
+        # Enforces aggregate bounds before a future agent can multiply the context cost.
+        super().__init__(
+            "The attachment bundle exceeds its shared limit.",
+            "The explicit attachment set exceeded the maximum file count or total byte budget, "
+            "so resolution stopped before agent execution. Aggregate limits keep multi-agent "
+            "commands from multiplying an unbounded context snapshot. Remove files or reduce "
+            "their size and retry.",
+            "Attach fewer or smaller files and retry.",
+        )
+
+
+class RuntimeAdmissionNotVerified(CliError):
+    """The layered admission gate did not admit the local runtime execution."""
+
+    code = CliErrorCode.OPERATION_FAILED
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+
+    def __init__(self, reason: str | None = None) -> None:
+        # Reports only the safe reason category, never a grant token or raw key.
+        detail = f" Reason: {reason}." if reason else ""
+        super().__init__(
+            "Runtime admission is not verified.",
+            description=(
+                "The layered runtime gate validates a typed grant, a signed grant_token, and its "
+                f"expiry before any local agent is spawned.{detail} No agent ran and no additional "
+                "credits beyond the admission attempt were spent. Provide a valid grant for the "
+                "requested capability or retry admission with the same idempotency key if the "
+                "previous attempt succeeded."
+            ),
+            trace=(
+                "RuntimeAdmissionGate.verify was called with the launch plan and admission grant "
+                "before RuntimeExecutor could run, and at least one layer did not admit."
+            ),
+        )
+
+
+class RuntimeExecutionNotImplemented(CliError):
+    """The command scaffold reached the deliberately absent runtime executor."""
+
+    code = CliErrorCode.NOT_IMPLEMENTED
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+
+    def __init__(self) -> None:
+        # Makes the no-charge boundary explicit for human and agent callers.
+        super().__init__(
+            "The adversarial-team runtime executor is not implemented yet.",
+            description=(
+                "The CLI validated the task, working directory, and native host, but this release "
+                "contains only the runtime platform scaffold. It stopped before requesting a paid "
+                "Vidbyte admission and before launching any local agent, so no credits were spent "
+                "and no machine state changed. Retrying cannot proceed until the executor ships."
+            ),
+            trace=(
+                "AdversarialTeamCommand built a RuntimeLaunchPlan and reached the "
+                "intentionally inert RuntimeExecutor."
+            ),
+            hint="Use 'vidbyte-cli runtime list' for published capability metadata.",
+        )
+
+
+class PersistenceExecutionNotImplemented(CliError):
+    """The command scaffold reached the deliberately absent persistence executor."""
+
+    code = CliErrorCode.NOT_IMPLEMENTED
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+
+    def __init__(self) -> None:
+        # Makes the no-charge boundary explicit for human and agent callers.
+        super().__init__(
+            "The persistence runtime executor is not implemented yet.",
+            description=(
+                "The CLI validated the task, working directory, native host, and strength "
+                "tier, but this release contains only the runtime platform scaffold. It "
+                "stopped before requesting a paid Vidbyte admission and before launching any "
+                "local agent, so no credits were spent and no machine state changed. Retrying "
+                "cannot proceed until the executor ships."
+            ),
+            trace=(
+                "PersistenceCommand built a RuntimeLaunchPlan and PersistenceSettings, then "
+                "reached the intentionally inert RuntimeExecutor."
+            ),
+            hint="Use 'vidbyte-cli runtime list' for published capability metadata.",
+        )
+
+
+class AmbiguousPromptSource(CliError):
+    """More than one prompt source was supplied for a single run."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(self) -> None:
+        super().__init__(
+            "Provide exactly one prompt source.",
+            description=(
+                "A positional prompt and --prompt-file were both supplied, and the CLI will not "
+                "guess which one the caller meant. Silently preferring one would make the same "
+                "command line mean different things across releases. Neither source was read, "
+                "so no file was opened and stdin was not consumed."
+            ),
+            trace=(
+                "The command adapter called PromptInputResolver.resolve, which checks source "
+                "exclusivity before touching any external input."
+            ),
+            hint="Use a positional prompt, --prompt-file PATH, or '-' for stdin.",
+        )
+
+
+class MissingPrompt(CliError):
+    """No prompt source was supplied and prompting is not implied by redirection."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(self) -> None:
+        super().__init__(
+            "A prompt is required.",
+            description=(
+                "The command needs prompt text and none of the three accepted sources was "
+                "supplied. Stdin is read only when '-' is passed explicitly, so a command whose "
+                "input happens to be redirected fails here instead of hanging on a read that "
+                "will never complete. Nothing was submitted to the backend."
+            ),
+            trace=(
+                "The command adapter called PromptInputResolver.resolve, which found neither a "
+                "positional value nor --prompt-file."
+            ),
+            hint="Pass a positional prompt, --prompt-file PATH, or '-' for stdin.",
+        )
+
+
+class PromptFileUnreadable(CliError):
+    """The path given to --prompt-file could not be opened or read."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(self, path: str, cause: Exception) -> None:
+        super().__init__(
+            f"Unable to read prompt file '{path}'.",
+            description=(
+                "The path passed to --prompt-file could not be opened for reading. It is "
+                "typically missing, a directory, or blocked by filesystem permissions. The "
+                "operating system's own message is withheld because it can expose unrelated "
+                "filesystem layout. Nothing was submitted to the backend."
+            ),
+            trace=(
+                "PromptInputResolver.resolve selected the file source and _read_file attempted "
+                "to open the path in UTF-8 text mode."
+            ),
+            hint="Check that the path exists and is a readable file.",
+            cause=cause,
+        )
+
+
+class PromptFileNotUtf8(CliError):
+    """The prompt file exists but is not valid UTF-8 text."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(self, cause: Exception) -> None:
+        super().__init__(
+            "The prompt file must contain valid UTF-8 text.",
+            description=(
+                "The file opened but its bytes did not decode as UTF-8. The CLI pins UTF-8 "
+                "rather than following the host locale so the same file produces the same run "
+                "on every machine. Re-save the file as UTF-8, or pass the prompt positionally. "
+                "No decoded content is echoed, because the file may hold sensitive text."
+            ),
+            trace=(
+                "PromptInputResolver.resolve selected the file source and _read_file decoded "
+                "the opened handle as UTF-8."
+            ),
+            cause=cause,
+        )
+
+
+class StandardInputNotText(CliError):
+    """Explicit stdin was requested but could not be decoded as text."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(self, cause: Exception) -> None:
+        super().__init__(
+            "Standard input must contain valid text.",
+            description=(
+                "'-' selected stdin as the prompt source, but the bytes arriving on that stream "
+                "did not decode as text. This usually means binary content was piped in, or the "
+                "producing process used an incompatible encoding. No content is echoed back, "
+                "because piped input may hold sensitive text."
+            ),
+            trace=(
+                "PromptInputResolver.resolve matched the '-' stdin marker and _read_stdin read "
+                "a bounded amount from the injected stdin stream."
+            ),
+            cause=cause,
+        )
+
+
+class EmptyPrompt(CliError):
+    """The resolved prompt held no non-whitespace content."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(self) -> None:
+        super().__init__(
+            "The prompt must not be empty.",
+            description=(
+                "The prompt source resolved successfully but contained only whitespace. An "
+                "empty prompt would consume credits for a run that cannot produce a useful "
+                "result, so it is rejected before submission. A file source that looks correct "
+                "in an editor may be empty because it was written but never flushed."
+            ),
+            trace=(
+                "PromptInputResolver.resolve read the selected source and passed the value to "
+                "_validate, which checks content before length."
+            ),
+        )
+
+
+class PromptTooLong(CliError):
+    """The resolved prompt exceeded the CLI's bounded input limit."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(self, limit: int) -> None:
+        super().__init__(
+            f"The prompt exceeds the {limit}-character limit.",
+            description=(
+                f"The resolved prompt was longer than the {limit}-character bound the CLI reads "
+                "from any source. The limit exists so a large or runaway file cannot be read "
+                "into memory in full before validation. Only the length is reported; the prompt "
+                "itself is never quoted back. Shorten the prompt or split the work into runs."
+            ),
+            trace=(
+                "PromptInputResolver.resolve read one character past the limit from the selected "
+                "source and passed the value to _validate."
+            ),
+        )
+
+
+class ConfigUnreadable(CliError):
+    """The stored configuration file could not be parsed against the version-one schema."""
+
+    code = CliErrorCode.CONFIG_INVALID
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+
+    def __init__(self, path: str, cause: Exception) -> None:
+        super().__init__(
+            "CLI configuration is invalid or uses an unsupported schema.",
+            description=(
+                "The configuration file exists but did not validate: it is unreadable, is not "
+                "JSON, exceeds the size bound, or declares a schema version this release does "
+                "not implement. The CLI never repairs or overwrites a file it cannot "
+                "understand, so nothing was changed and no command ran."
+            ),
+            trace=(
+                "ConfigStore.load selected the native or legacy configuration path and _read "
+                "decoded its bytes and validated them as a ConfigDocument."
+            ),
+            hint=f"Repair or move the configuration file at {path}.",
+            cause=cause,
+        )
+
+
+class ConfigInvalidBeforeWrite(CliError):
+    """The configuration on disk stopped validating between this command's read and write."""
+
+    code = CliErrorCode.CONFIG_INVALID
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+
+    def __init__(self, path: str, cause: Exception) -> None:
+        super().__init__(
+            "CLI configuration changed to an invalid or unsupported schema.",
+            description=(
+                "The configuration validated when this command read it and no longer does, so "
+                "another process or a manual edit replaced it mid-command. The write was "
+                "abandoned before touching the file: the new content is intact and the setting "
+                "you asked for was not applied."
+            ),
+            trace=(
+                "ConfigStore.save called _native_digest to re-read the current file for "
+                "conflict detection, and that re-read failed validation."
+            ),
+            hint=f"Repair or move the configuration file at {path}.",
+            cause=cause,
+        )
+
+
+class ConfigWriteConflict(CliError):
+    """The configuration file changed after this command read it."""
+
+    code = CliErrorCode.CONFIG_WRITE_CONFLICT
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+    retryable = True
+
+    def __init__(self) -> None:
+        super().__init__(
+            "CLI configuration changed during this command.",
+            description=(
+                "Writing a setting is a read-modify-write, and the file no longer matches what "
+                "this command read. Completing the write would silently discard whatever the "
+                "other writer stored. Nothing was written, so the other change is intact and "
+                "re-running against the current file is safe."
+            ),
+            trace=(
+                "ConfigStore.save compared the digest captured by the caller's read against a "
+                "fresh digest of the native configuration file and found them different."
+            ),
+            hint="Run the command again against the latest configuration.",
+        )
+
+
+class InvalidConfigValue(CliError):
+    """`config set` was given a value the field's schema rejects."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(self, field: str, cause: Exception) -> None:
+        super().__init__(
+            f"Invalid value for configuration field '{field}'.",
+            description=(
+                f"The value supplied for '{field}' failed the same validation the persisted "
+                "document uses, so accepting it would write a profile the CLI could not load "
+                "back. Nothing was written. The underlying validation detail is withheld "
+                "because it quotes the value, which may have been mistyped from a secret."
+            ),
+            trace=(
+                "ConfigSetCommand.execute called ConfigStore.set, whose _updated_profile "
+                "revalidated the whole profile with the new field value applied."
+            ),
+            hint="Run 'vidbyte-cli config get' to inspect the current profile value.",
+            cause=cause,
+        )
+
+
+class InvalidConfigOverride(CliError):
+    """An environment or command-line configuration value could not be parsed."""
+
+    code = CliErrorCode.CONFIG_INVALID
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+
+    def __init__(self, cause: Exception) -> None:
+        super().__init__(
+            "An environment or command configuration value is invalid.",
+            description=(
+                "Resolution combines command options, VIDBYTE_* variables, and the selected "
+                "profile, and one supplied value did not parse into its declared type. The "
+                "offending value is not echoed, because variables in the same namespace hold "
+                "credentials. No command ran and no local state changed."
+            ),
+            trace=(
+                "ConfigResolver.resolve applied command → environment → profile precedence per "
+                "field and constructed the ResolvedConfig from the winning values."
+            ),
+            hint="Check VIDBYTE_* settings and the selected CLI profile.",
+            cause=cause,
+        )
+
+
+class StateWriteThroughSymlink(CliError):
+    """A local state path the CLI was about to replace is a symbolic link."""
+
+    code = CliErrorCode.CONFIG_INVALID
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+
+    def __init__(self) -> None:
+        super().__init__(
+            "Refusing to write CLI state through a symbolic link.",
+            description=(
+                "The target path is a symbolic link, and the CLI writes state by replacing a "
+                "file atomically. Whether that replaces the link or the file it points at "
+                "varies by platform, which is not a strong enough guarantee for a path that "
+                "may hold a credential. Nothing was written and the link is untouched."
+            ),
+            trace=(
+                "A store encoded its document and called AtomicFileWriter.write, which checks "
+                "the destination for a symbolic link before creating its temporary sibling."
+            ),
+            hint="Replace the symbolic link with a regular file and retry.",
+        )
+
+
+class StateWriteFailed(CliError):
+    """The operating system refused a local state write."""
+
+    code = CliErrorCode.OPERATION_FAILED
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+    retryable = True
+
+    def __init__(self, cause: Exception) -> None:
+        super().__init__(
+            "CLI state could not be saved.",
+            description=(
+                "Creating, flushing, or replacing the state file failed at the filesystem "
+                "level — typically permissions, a read-only or full volume, or a parent "
+                "directory the CLI may not create. The temporary sibling was removed, so the "
+                "previous file is intact and the operation had no partial effect."
+            ),
+            trace=(
+                "AtomicFileWriter.write created a randomized sibling file, wrote and fsynced "
+                "it, and attempted os.replace onto the destination."
+            ),
+            hint="Check directory ownership and available disk space, then retry.",
+            cause=cause,
+        )
+
+
+class LocalFileReadFailed(CliError):
+    """A local file exists but could not be read, decoded, or parsed."""
+
+    code = CliErrorCode.OPERATION_FAILED
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+
+    def __init__(self, name: str, reason: str, cause: Exception) -> None:
+        # The reason is a fixed category chosen by LocalFileStore, never the OS message, so
+        # callers can re-raise it with their own context without leaking absolute paths.
+        super().__init__(
+            f"Could not read {name}: {reason}.",
+            description=(
+                "The file exists, so this is not a missing-file case: opening, decoding, or "
+                f"parsing it failed because {reason}. Nothing was changed on disk. Retrying "
+                "without changing anything will fail the same way, so repair the file or its "
+                "permissions first, or point the command at a different location."
+            ),
+            trace="LocalFileStore read the file as UTF-8 text and, for JSON, parsed it.",
+            hint="Check the file's permissions and contents, then retry.",
+            cause=cause,
+        )
+        self.reason = reason
+
+
+class LocalFileWriteFailed(CliError):
+    """The operating system refused to create, replace, append to, or copy a local file."""
+
+    code = CliErrorCode.OPERATION_FAILED
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+
+    def __init__(self, name: str, reason: str, cause: Exception) -> None:
+        # Same fixed-category contract as LocalFileReadFailed, for the write direction.
+        super().__init__(
+            f"Could not write {name}: {reason}.",
+            description=(
+                f"Writing the file failed at the filesystem level because {reason}. Replacing "
+                "writes go through a temporary sibling, so the previous version of the file, "
+                "if any, is intact and no partial file was left behind. Retrying helps only "
+                "after the cause is fixed, such as freeing space or choosing a writable path."
+            ),
+            trace="LocalFileStore created parent directories and wrote through a temp sibling.",
+            hint="Check directory permissions and free space, or choose another destination.",
+            cause=cause,
+        )
+        self.reason = reason
+
+
+class LocalDocumentInvalid(CliError):
+    """A local JSON document was readable but did not satisfy the caller's document model."""
+
+    code = CliErrorCode.OPERATION_FAILED
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+
+    def __init__(self, name: str, reason: str, cause: Exception | None = None) -> None:
+        # Same fixed-category contract as LocalFileReadFailed: the reason is authored text chosen
+        # by LocalDocumentStore, never a validator message that could quote document contents.
+        super().__init__(
+            f"Local document {name} is invalid: {reason}.",
+            description=(
+                "The file could be addressed, but its contents are not a document the command "
+                f"can use because {reason}. Nothing was changed on disk, and the document was "
+                "not replaced with an empty default. Retrying without repairing or removing the "
+                "document will fail the same way."
+            ),
+            trace="LocalDocumentStore bounded, parsed, and validated the document against a model.",
+            hint="Repair the document so it matches its schema, or remove it, then retry.",
+            cause=cause,
+        )
+        self.reason = reason
+
+
+class MigrationVerificationFailed(CliError):
+    """Legacy state was copied but the copy did not read back identically."""
+
+    code = CliErrorCode.OPERATION_FAILED
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+
+    def __init__(self) -> None:
+        super().__init__(
+            "Legacy CLI state could not be verified after migration.",
+            description=(
+                "Migration copies each item and reads it back to prove the copy is identical, "
+                "and one read-back disagreed. Migration never deletes, so the legacy tree under "
+                "~/.vidbyte is exactly as it was. The native location may hold a partial copy, "
+                "which later runs overwrite rather than trust."
+            ),
+            trace=(
+                "StateMigration.migrate_if_needed copied the legacy configuration or the "
+                "legacy credential and compared each destination against its source."
+            ),
+            hint="The legacy files were preserved; retry after checking local storage.",
+        )
+
+
+class CredentialStoreUnavailable(CliError):
+    """The operating-system keyring could not be used for this operation."""
+
+    code = CliErrorCode.CREDENTIAL_STORE_UNAVAILABLE
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+
+    def __init__(self, cause: Exception | None = None) -> None:
+        super().__init__(
+            "The operating-system credential store is unavailable.",
+            description=(
+                "No keyring backend reported itself usable, or the backend rejected the "
+                "operation — a locked keychain, a headless session with no agent, or a write "
+                "that did not read back as written. The backend's own message is withheld "
+                "because it can quote account identifiers. No credential was stored or read."
+            ),
+            trace=(
+                "KeyringCredentialStore resolved the active backend and performed a scoped "
+                "get, set, or delete against the 'vidbyte-cli' service."
+            ),
+            hint="Check the system keyring, or explicitly approve the restricted-file fallback.",
+            cause=cause,
+        )
+
+
+class NoApprovedCredentialStore(CliError):
+    """No keyring exists and restricted-file storage was not approved."""
+
+    code = CliErrorCode.CREDENTIAL_STORE_UNAVAILABLE
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+
+    def __init__(self) -> None:
+        super().__init__(
+            "No usable OS credential store is available.",
+            description=(
+                "The key verified successfully but has nowhere approved to live. This machine "
+                "exposes no working keyring, and the restricted-file fallback keeps the key "
+                "readable to your account, so the CLI will not select it on your behalf. "
+                "Nothing was written; the verified key was discarded with this process."
+            ),
+            trace=(
+                "LoginCommand.execute verified the credential and called CredentialStore.write, "
+                "which found no available keyring and no file-fallback consent."
+            ),
+            hint="Retry login and explicitly approve the restricted-file fallback.",
+        )
+
+
+class StoredCredentialUnreadable(CliError):
+    """The restricted fallback credential file could not be parsed."""
+
+    code = CliErrorCode.CREDENTIAL_STORE_UNAVAILABLE
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+
+    def __init__(self, cause: Exception) -> None:
+        super().__init__(
+            "Stored CLI credentials are invalid or unavailable.",
+            description=(
+                "The fallback credential file exists but is unreadable, is not JSON, exceeds "
+                "the size bound, or declares an unsupported schema version. The CLI will not "
+                "rewrite a credential file it cannot understand, because that could destroy a "
+                "key it merely failed to parse. No credential was resolved."
+            ),
+            trace=(
+                "FileCredentialStore._load read the restricted credential file and validated "
+                "it as a version-one CredentialDocument."
+            ),
+            hint="Move the fallback credential file and run 'vidbyte-cli login' again.",
+            cause=cause,
+        )
+
+
+class LegacyCredentialUnreadable(CliError):
+    """The ~/.vidbyte credential file exists but could not be validated."""
+
+    code = CliErrorCode.CREDENTIAL_STORE_UNAVAILABLE
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+
+    def __init__(self, cause: Exception) -> None:
+        super().__init__(
+            "Legacy CLI credentials are invalid or unavailable.",
+            description=(
+                "A credential file remains at the historical ~/.vidbyte location and did not "
+                "validate, so it can be neither read nor migrated. It is reported rather than "
+                "skipped, because ignoring it would leave a file that looks like a working "
+                "login. It was not modified or removed."
+            ),
+            trace=(
+                "A credential read or migration reached the legacy credential path and decoded "
+                "its bytes as a Credentials document."
+            ),
+            hint="Run 'vidbyte-cli login' to replace the stored credential.",
+            cause=cause,
+        )
+
+
+class LegacyCredentialSymlink(CliError):
+    """Logout was asked to remove a legacy credential file that is a symbolic link."""
+
+    code = CliErrorCode.CREDENTIAL_STORE_UNAVAILABLE
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+
+    def __init__(self) -> None:
+        super().__init__(
+            "Refusing to remove legacy credentials through a symbolic link.",
+            description=(
+                "Logout deletes the legacy credential file so a stale key cannot become active "
+                "again, but that path is a symbolic link: unlinking it would remove the link "
+                "and leave whatever it points at. The CLI will not guess which one was meant. "
+                "The scoped keyring and fallback entries were still cleared."
+            ),
+            trace=(
+                "LogoutCommand.execute called CredentialStore.clear, whose clear_legacy step "
+                "checked the legacy credential path before unlinking it."
+            ),
+            hint="Remove the symbolic link manually after verifying its target.",
+        )
+
+
+class LegacyCredentialRemovalFailed(CliError):
+    """The legacy credential file could not be deleted during logout."""
+
+    code = CliErrorCode.CREDENTIAL_STORE_UNAVAILABLE
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+    retryable = True
+
+    def __init__(self, cause: Exception) -> None:
+        super().__init__(
+            "Legacy credentials could not be removed.",
+            description=(
+                "The legacy credential file exists and the filesystem refused to unlink it, "
+                "usually because of directory permissions or another process holding it open. "
+                "This is a failure rather than a skip, because the file can still authenticate "
+                "later invocations. Scoped credentials were already cleared."
+            ),
+            trace=(
+                "LogoutCommand.execute called CredentialStore.clear, whose clear_legacy step "
+                "attempted to unlink the legacy credential path."
+            ),
+            hint="Check the legacy file permissions and retry logout.",
+            cause=cause,
+        )
+
+
+class InvalidEnvironmentApiKey(CliError):
+    """VIDBYTE_API_KEY is set but holds nothing usable."""
+
+    code = CliErrorCode.AUTH_REQUIRED
+    exit_status = ExitCode.AUTHENTICATION
+
+    def __init__(self) -> None:
+        super().__init__(
+            "VIDBYTE_API_KEY is empty or invalid.",
+            description=(
+                "The environment variable is set to an empty, whitespace-only, or oversized "
+                "value. Because it is set it outranks the keyring and the fallback file, so "
+                "falling through to stored credentials would authenticate as somebody the "
+                "caller did not ask for. The value is never echoed back."
+            ),
+            trace=(
+                "CredentialResolver.resolve read VIDBYTE_API_KEY from the injected environment "
+                "and bounds-checked it before any store was consulted."
+            ),
+            hint="Set a valid key or remove the variable to use stored credentials.",
+        )
+
+
+class EnvironmentApiKeyNotLive(CliError):
+    """VIDBYTE_API_KEY holds a well-formed value that is not a live Vidbyte key."""
+
+    code = CliErrorCode.AUTH_REQUIRED
+    exit_status = ExitCode.AUTHENTICATION
+
+    def __init__(self) -> None:
+        super().__init__(
+            "VIDBYTE_API_KEY is not a live Vidbyte API key.",
+            description=(
+                "The variable holds a syntactically usable value that does not begin with the "
+                "live-key prefix. The backend extracts only live keys, so such a value produces "
+                "no credential at all and every request would be answered as unauthenticated "
+                "rather than as a bad key. It is rejected here so the cause is visible instead "
+                "of surfacing later as an unexplained login prompt. The value is never echoed."
+            ),
+            trace=(
+                "CredentialResolver.resolve read VIDBYTE_API_KEY from the injected environment "
+                "and checked its format before any credential store was consulted."
+            ),
+            hint="Export a live key from the Vidbyte dashboard, or unset the variable.",
+        )
+
+
+class NoninteractiveLoginRequiresToken(CliError):
+    """Login had no terminal to prompt on and no explicit token source."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(self) -> None:
+        super().__init__(
+            "Login requires explicit token input in noninteractive mode.",
+            description=(
+                "The hidden prompt needs an interactive terminal, and this invocation has none "
+                "or passed --no-input. Stdin is read only when --with-token says so, so a "
+                "redirected stream is never consumed by accident and the command cannot hang "
+                "on a read that will not complete. No credential was stored."
+            ),
+            trace=(
+                "LoginCommand.execute called CredentialInput.read without the stdin marker, "
+                "which checked --no-input and the detected terminal capabilities."
+            ),
+            hint="Pipe the token to 'vidbyte-cli login --with-token'.",
+        )
+
+
+class InvalidApiKeyInput(CliError):
+    """The token supplied to login was empty or beyond the input bound."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(self) -> None:
+        super().__init__(
+            "The supplied Vidbyte API key is empty or too large.",
+            description=(
+                "The value read from the prompt or from stdin was blank after trimming, or "
+                "longer than the 4096-character bound the CLI reads from any secret source. "
+                "That bound keeps an accidental file redirect from being pulled into memory as "
+                "a key. The value is never echoed, and nothing was verified or stored."
+            ),
+            trace=(
+                "CredentialInput.read consumed the selected input channel and bounds-checked "
+                "the trimmed value before constructing Credentials."
+            ),
+            hint="Paste the key from the Vidbyte dashboard, or pipe it with --with-token.",
+        )
+
+
+class ApiKeyNotLiveFormat(CliError):
+    """The token supplied to login is not a live Vidbyte API key."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(self) -> None:
+        super().__init__(
+            "The supplied value is not a live Vidbyte API key.",
+            description=(
+                "The value read from the prompt or from stdin does not begin with the live-key "
+                "prefix. The backend extracts only live keys, so storing this one would leave "
+                "every later command answered as unauthenticated with nothing to point at. It "
+                "is refused before verification, so nothing was sent and nothing was stored. "
+                "The value is never echoed, because a mistyped secret is still a secret."
+            ),
+            trace=(
+                "CredentialInput.read consumed the selected input channel, bounds-checked the "
+                "trimmed value, and asked Credentials.is_live_format about its prefix."
+            ),
+            hint="Copy a live API key from the Vidbyte dashboard and run login again.",
+        )
+
+
+class FileFallbackNotApproved(CliError):
+    """Login could not ask for fallback consent and none was given on the command line."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(self) -> None:
+        super().__init__(
+            "No OS keyring is available and file storage was not approved.",
+            description=(
+                "Storing the key would require the restricted-file fallback, which the CLI uses "
+                "only with explicit consent. This invocation is noninteractive, so the "
+                "confirmation prompt cannot be shown and consent has to arrive as a flag. "
+                "Nothing was stored."
+            ),
+            trace=(
+                "LoginCommand.execute called _fallback_consent, which found no available "
+                "keyring, no --allow-file-fallback, and no interactive terminal."
+            ),
+            hint="Retry with --allow-file-fallback after reviewing the storage warning.",
+        )
+
+
+class ApiRouteMisconfigured(CliError):
+    """A CLI-owned route string was not a usable relative API path."""
+
+    code = CliErrorCode.INTERNAL_ERROR
+    exit_status = ExitCode.SOFTWARE
+
+    def __init__(self) -> None:
+        super().__init__(
+            "An invalid API route was configured in the CLI.",
+            description=(
+                "Every request path is built from constants this CLI ships, and one of them was "
+                "not a single relative path rooted at '/'. A path carrying its own scheme or "
+                "host would send the API key to an origin the caller never configured, so the "
+                "request is refused rather than sent. This is a CLI defect, not an invocation "
+                "mistake, and no arguments can work around it."
+            ),
+            trace=(
+                "An endpoint group called ApiClient.request, whose _url rejected the path "
+                "before any connection was opened."
+            ),
+            hint="Report this with the command you ran; no argument change will help.",
+        )
+
+
+class ApiResponseUnsupported(CliError):
+    """The backend replied with something this CLI cannot decode."""
+
+    code = CliErrorCode.API_PROTOCOL_ERROR
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+
+    def __init__(self, request_id: str | None = None, cause: Exception | None = None) -> None:
+        super().__init__(
+            "The Vidbyte API returned an unsupported response.",
+            description=(
+                "The request succeeded at the HTTP level, but the reply was not JSON of the "
+                "shape this CLI release expects: a wrong content type, an empty or oversized "
+                "body, or fields that failed validation. The body is not quoted back, because a "
+                "response may carry account content. A newer backend usually means this CLI is "
+                "out of date; retrying an unchanged command will produce the same result."
+            ),
+            trace=(
+                "ApiClient received a success status and handed the response to "
+                "ResponseDecoder, which bounded and validated it before returning typed data."
+            ),
+            hint="Upgrade the CLI. If it is current, report the request ID.",
+            request_id=request_id,
+            cause=cause,
+        )
+
+
+class ApiUnreachable(CliError):
+    """The Vidbyte API could not be contacted at all."""
+
+    code = CliErrorCode.API_UNAVAILABLE
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+    retryable = True
+
+    def __init__(self, cause: Exception) -> None:
+        super().__init__(
+            "The Vidbyte API could not be reached.",
+            description=(
+                "Connecting to the configured API host failed, or the connection was lost "
+                "before a reply arrived — typically no network route, DNS failure, a proxy, or "
+                "a timeout. The transport error is withheld because it quotes the URL and may "
+                "quote proxy configuration. Safe requests were already retried, so the failure "
+                "persisted across every attempt."
+            ),
+            trace=(
+                "ApiClient._send exhausted RetryPolicy and raised through "
+                "ApiProblemMapper.from_transport without receiving any HTTP response."
+            ),
+            hint="Check connectivity and 'vidbyte-cli config get api_url', then retry.",
+            cause=cause,
+        )
+
+
+class ApiRouteMissing(CliError):
+    """The configured host does not serve the route the CLI asked for."""
+
+    code = CliErrorCode.API_UNAVAILABLE
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+
+    def __init__(self, request_id: str | None = None) -> None:
+        super().__init__(
+            "The Vidbyte API does not serve this route.",
+            description=(
+                "The host answered but has no handler at the requested path, so it is either "
+                "not the Vidbyte API or is running a release older than this CLI expects. This "
+                "says nothing about your API key, which was never evaluated. Nothing was "
+                "stored. Changing the key will not help; the configured API URL or the "
+                "deployed backend has to change."
+            ),
+            trace=(
+                "ApiClient.post_direct received a response outside the success range and "
+                "ApiProblemMapper classified its 404 status as a missing route."
+            ),
+            hint="Check 'vidbyte-cli config get api_url', then upgrade the CLI if it is correct.",
+            request_id=request_id,
+        )
+
+
+class ApiCredentialsRejected(CliError):
+    """The backend refused the API key this invocation presented."""
+
+    code = CliErrorCode.AUTH_REQUIRED
+    exit_status = ExitCode.AUTHENTICATION
+
+    def __init__(self, request_id: str | None = None) -> None:
+        super().__init__(
+            "The Vidbyte API rejected the current credentials.",
+            description=(
+                "A key was found and sent, and the backend did not accept it as an "
+                "authenticated caller. The key is usually revoked, expired, or issued for a "
+                "different host than the one configured for this profile. Nothing was submitted "
+                "and no credits were spent. The key value is never echoed."
+            ),
+            trace=(
+                "ApiClient sent the resolved credential in the x-api-key header and the "
+                "backend answered with an unauthenticated status."
+            ),
+            hint="Run 'vidbyte-cli login' for the selected profile, then retry.",
+            request_id=request_id,
+        )
+
+
+class ApiPermissionDenied(CliError):
+    """The key authenticated but lacks the scope this route requires."""
+
+    code = CliErrorCode.AUTH_REQUIRED
+    exit_status = ExitCode.AUTHENTICATION
+
+    def __init__(self, request_id: str | None = None) -> None:
+        super().__init__(
+            "The API key is missing the scope this command requires.",
+            description=(
+                "The backend recognized the key and then refused the route, which means the "
+                "credential is valid but not authorized for it. Research reads need the "
+                "'research:read' scope and research mutations need 'research:write'. Logging in "
+                "again will not help, because the same key would be stored; the scope has to be "
+                "granted where the key was issued. Nothing was submitted and no credits were "
+                "spent."
+            ),
+            trace=(
+                "ApiClient sent an authenticated request and the backend gatekeeper rejected "
+                "it after identifying the caller but before running the route."
+            ),
+            hint="Grant the required scope to this key in the Vidbyte dashboard.",
+            request_id=request_id,
+        )
+
+
+class ApiCreditExhausted(CliError):
+    """The account cannot fund the requested operation."""
+
+    code = CliErrorCode.CREDIT_EXHAUSTED
+    exit_status = ExitCode.CREDIT_EXHAUSTED
+
+    def __init__(
+        self,
+        request_id: str | None = None,
+        remediation: dict[str, JsonValue] | None = None,
+    ) -> None:
+        super().__init__(
+            "The Vidbyte account does not have enough API balance for this operation.",
+            description=(
+                "Vidbyte could not reserve admission or extend the API-balance budget for this "
+                "agent operation. If this happened before start, no agent was started and no "
+                "new Vidbyte usage was charged. If a run was already in progress, earlier work "
+                "may already have been charged, so do not duplicate it blindly. This is a "
+                "Vidbyte API-balance problem, not a shortage in the model provider account. "
+                "First stop retrying this operation or sending more turns. Then get explicit "
+                "approval from the user before spending money. Use the same authenticated "
+                "Vidbyte API key that made the failed request, create one fresh idempotency key "
+                "for the top-up, and send POST /agent/topup. Follow the returned payment "
+                "challenge and authorize only that exact challenge with x402 or MPP; do not "
+                "invent a different amount, route, or recipient. Resend the identical top-up "
+                "request with the payment authorization. Confirm that the response reports "
+                "credited_cents and available_balance_cents, and that the available balance "
+                "covers the original or remaining operation. If it does not, obtain approval "
+                "before another top-up. After the balance is confirmed, retry or resume the "
+                "original operation and reuse its original idempotency key when one was supplied. "
+                "If the agent cannot make the payment, ask the user to add API balance at "
+                "https://vidbyte.pro/settings/api. Never expose the API key or payment private "
+                "key in a prompt, log, error report, or agent task. Status 5 is distinct from "
+                "an ordinary failure so a caller can branch on this recovery path."
+            ),
+            trace=(
+                "ApiClient submitted a priced mutation and the backend refused admission at "
+                "the wallet rail before reserving usage."
+            ),
+            hint=(
+                "Get user approval, run `vidbyte-cli billing top-up --confirm`, verify the "
+                "credited balance, then retry the original operation."
+            ),
+            request_id=request_id,
+            remediation=remediation,
+        )
+
+
+class BillingTopUpApprovalRequired(CliError):
+    """The explicit top-up command was not given its payment confirmation."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(self) -> None:
+        super().__init__(
+            "Confirm before purchasing Vidbyte API balance.",
+            description=(
+                "The billing top-up command creates a paid x402 authorization and credits "
+                "the authenticated Vidbyte account. It will not spend money unless the "
+                "caller explicitly supplies --confirm, so an agent must obtain user approval "
+                "before invoking it."
+            ),
+            trace=(
+                "BillingTopUpCommand stopped before resolving the payment signer or "
+                "sending a request."
+            ),
+            hint="Obtain user approval, then rerun `vidbyte-cli billing top-up --confirm`.",
+        )
+
+
+class ApiResourceNotFound(CliError):
+    """The addressed resource does not exist for this caller."""
+
+    code = CliErrorCode.OPERATION_FAILED
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+
+    def __init__(self, request_id: str | None = None) -> None:
+        super().__init__(
+            "The requested Vidbyte resource was not found.",
+            description=(
+                "No record with that identifier is visible to this account. Reads are scoped to "
+                "the caller, so a resource owned by somebody else is indistinguishable from one "
+                "that never existed, and a deleted thread reads the same way. Check the "
+                "identifier came from this CLI's own output rather than from a browser URL or "
+                "an internal tool."
+            ),
+            trace=(
+                "ApiClient sent an owner-scoped read or mutation and the backend found no "
+                "matching record for the authenticated caller."
+            ),
+            hint="Run 'vidbyte-cli research threads' to list the identifiers you can use.",
+            request_id=request_id,
+        )
+
+
+class ApiRequestRejected(CliError):
+    """The backend refused the request as invalid."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(self, request_id: str | None = None) -> None:
+        super().__init__(
+            "The Vidbyte API rejected the request.",
+            description=(
+                "One or more supplied values failed the backend's own validation, so the "
+                "operation never started and nothing was charged. The backend's field-level "
+                "detail is withheld because it quotes the submitted values, which may include "
+                "the prompt. The usual causes are a domain filter the backend has not reviewed, "
+                "a date outside the accepted range, or a bound the CLI does not yet enforce "
+                "locally."
+            ),
+            trace=(
+                "ApiClient submitted the encoded request body and the backend answered with a "
+                "client-side validation status before the operation ran."
+            ),
+            hint="Re-run with fewer options to isolate the rejected value.",
+            request_id=request_id,
+        )
+
+
+class ApiRequestConflicted(CliError):
+    """The resource is not in a state that permits this operation."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(self, request_id: str | None = None) -> None:
+        super().__init__(
+            "The run is not in a state that can be continued.",
+            description=(
+                "Continuing a run is legal only after it has already settled badly — partial, "
+                "failed, or out of credit. A run that is still admitting or running has not "
+                "finished, and a run that completed has nothing left to continue. Nothing was "
+                "admitted and no credits were spent. Read the run first and continue it only "
+                "once its status is one of the three resumable ones."
+            ),
+            trace=(
+                "ApiClient submitted a continuation and the backend compared the stored run "
+                "status against its terminal-resumable set before admitting any work."
+            ),
+            hint="Run 'vidbyte-cli research status <run_id>' to see the current status.",
+            request_id=request_id,
+        )
+
+
+class ApiRateLimited(CliError):
+    """The account's request budget for this window is spent."""
+
+    code = CliErrorCode.API_UNAVAILABLE
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+    retryable = True
+
+    def __init__(self, request_id: str | None = None, retry_after: int | None = None) -> None:
+        wait = (
+            f"Wait {retry_after} seconds before retrying."
+            if retry_after is not None
+            else "Wait a minute before retrying, and avoid polling faster than every 10s."
+        )
+        super().__init__(
+            "The Vidbyte API request budget for this key is exhausted.",
+            description=(
+                "Requests are rate limited per key on a weighted per-minute budget, and "
+                "starting a research run costs far more of that budget than reading one. The "
+                "CLI already retried within its own bound and the limit still applied, so "
+                "nothing was submitted. Waiting a minute is usually enough; polling in a tight "
+                "loop is what exhausts the budget in the first place."
+            ),
+            trace=(
+                "ApiClient exhausted RetryPolicy against a rate-limited status and raised "
+                "through ApiProblemMapper.from_response."
+            ),
+            hint=wait,
+            request_id=request_id,
+        )
+
+
+class ApiUnavailable(CliError):
+    """The backend failed to serve the request."""
+
+    code = CliErrorCode.API_UNAVAILABLE
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+    retryable = True
+
+    def __init__(self, request_id: str | None = None) -> None:
+        super().__init__(
+            "The Vidbyte API is temporarily unavailable.",
+            description=(
+                "The backend accepted the connection and then failed while handling the "
+                "request. Safe requests were already retried within this invocation and the "
+                "failure persisted. Whether the operation took effect is unknown for a "
+                "mutation, so re-run it with the same --idempotency-key rather than a fresh "
+                "one if you need to be certain it happens exactly once."
+            ),
+            trace=(
+                "ApiClient exhausted RetryPolicy against a server-error status and raised "
+                "through ApiProblemMapper.from_response."
+            ),
+            hint="Retry after a short delay; reuse --idempotency-key for a mutation.",
+            request_id=request_id,
+        )
+
+
+class ApiOperationFailed(CliError):
+    """The backend answered with a status this CLI does not classify."""
+
+    code = CliErrorCode.OPERATION_FAILED
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+
+    def __init__(self, request_id: str | None = None) -> None:
+        super().__init__(
+            "The Vidbyte API could not complete the operation.",
+            description=(
+                "The reply carried a failure status that this CLI release has no specific "
+                "handling for, so it is reported without guessing at a cause. The response body "
+                "is not quoted, because it may carry account content. Whether the operation "
+                "took effect is unknown; read the resource before retrying a mutation."
+            ),
+            trace=(
+                "ApiClient received a non-success status that matched no specific arm of "
+                "ApiProblemMapper.from_response."
+            ),
+            hint="Retry once, then report the request ID if the problem continues.",
+            request_id=request_id,
+        )
+
+
+class ResearchThreadIdInvalid(CliError):
+    """A supplied thread identifier is not a public thread share token."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(self) -> None:
+        super().__init__(
+            "That is not a valid research thread ID.",
+            description=(
+                "A research thread is addressed only by the public share token the API "
+                "publishes, which is a UUID. The value supplied does not have that shape, so it "
+                "is refused here rather than spent on a request the backend would reject during "
+                "path validation. The most common cause is pasting an internal identifier from "
+                "another tool. Nothing was submitted and no credits were spent."
+            ),
+            trace=(
+                "The research command parsed its arguments and called ThreadId.parse before "
+                "resolving credentials or constructing an API client."
+            ),
+            hint="Run 'vidbyte-cli research threads' and copy the ID it prints.",
+        )
+
+
+class ResearchIdempotencyKeyInvalid(CliError):
+    """An explicit --idempotency-key was outside the accepted format."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(self) -> None:
+        super().__init__(
+            "The idempotency key must be 8-128 URL-safe characters.",
+            description=(
+                "An explicit idempotency key is what lets a priced mutation be retried without "
+                "being charged twice, so it has to survive a URL and an HTTP header unchanged. "
+                "Letters, digits, period, underscore, colon, and hyphen are accepted. The "
+                "supplied value is refused before the request is built, so nothing was "
+                "submitted. Omit the option entirely to have one generated."
+            ),
+            trace=(
+                "The command called IdempotencyKey.create with the explicit "
+                "--idempotency-key value before any credential was resolved."
+            ),
+            hint="Pass a UUID, or omit --idempotency-key to generate one.",
+        )
+
+
+class StoredProviderCredentialUnreadable(CliError):
+    """The provider fallback credential file could not be parsed."""
+
+    code = CliErrorCode.CREDENTIAL_STORE_UNAVAILABLE
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+
+    def __init__(self, cause: Exception) -> None:
+        super().__init__(
+            "Stored provider credentials are invalid or unavailable.",
+            description=(
+                "The provider fallback file exists but is unreadable, is not JSON, exceeds "
+                "the size bound, or declares an unsupported schema version. The CLI will not "
+                "rewrite a file it cannot understand. No provider credential was resolved."
+            ),
+            trace=(
+                "FileProviderStore._load read the provider credential file and validated "
+                "it as a version-one ProviderDocument."
+            ),
+            hint="Move the fallback file and run 'vidbyte-cli provider login <provider>' again.",
+            cause=cause,
+        )
+
+
+class ProviderStoreUnavailable(CliError):
+    """The OS keyring for provider keys could not be used."""
+
+    code = CliErrorCode.CREDENTIAL_STORE_UNAVAILABLE
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+
+    def __init__(self, cause: Exception | None = None) -> None:
+        super().__init__(
+            "The provider credential store is unavailable.",
+            description=(
+                "No keyring backend reported itself usable, or the backend rejected the "
+                "operation — a locked keychain or a headless session with no agent. No "
+                "provider credential was stored or read."
+            ),
+            trace=(
+                "KeyringProviderStore performed a scoped get, set, or delete against "
+                "the 'vidbyte-cli-provider' service."
+            ),
+            hint="Check the system keyring, or approve the restricted-file fallback.",
+            cause=cause,
+        )
+
+
+class NoApprovedProviderStore(CliError):
+    """No keyring and file fallback was not approved for provider storage."""
+
+    code = CliErrorCode.CREDENTIAL_STORE_UNAVAILABLE
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+
+    def __init__(self, provider: str) -> None:
+        super().__init__(
+            f"No approved storage for provider '{provider}'.",
+            description=(
+                "The provider key verified successfully but has nowhere approved to live. "
+                "This machine exposes no working keyring, and the restricted-file fallback "
+                "requires explicit consent. Nothing was written; the verified key was "
+                "discarded with this process."
+            ),
+            trace=(
+                "ProviderLoginCommand verified the credential and called "
+                "ProviderCredentialStore.write, which found no available keyring and no "
+                "file-fallback consent."
+            ),
+            hint="Retry with --allow-file-fallback.",
+        )
+
+
+class ProviderCredentialsRejected(CliError):
+    """The provider rejected the supplied API key."""
+
+    code = CliErrorCode.AUTH_REQUIRED
+    exit_status = ExitCode.AUTHENTICATION
+
+    def __init__(self, provider: str) -> None:
+        super().__init__(
+            f"The {provider} provider rejected the API key.",
+            description=(
+                "A provider key was sent and the provider answered 401 or 403. The key is "
+                "revoked, expired, or malformed. Nothing was stored and no Vidbyte credits "
+                "were spent. The key value is never echoed."
+            ),
+            trace=(
+                "ProviderVerifier sent the key to the provider's /v1/models and the "
+                "provider answered with an unauthenticated status."
+            ),
+            hint=f"Run 'vidbyte-cli provider login {provider}' with a valid key.",
+        )
+
+
+class ProviderApiUnreachable(CliError):
+    """The provider API could not be contacted at all."""
+
+    code = CliErrorCode.API_UNAVAILABLE
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+    retryable = True
+
+    def __init__(self, provider: str, cause: Exception | None = None) -> None:
+        super().__init__(
+            f"The {provider} provider API could not be reached.",
+            description=(
+                "Connecting to the provider failed, or the connection was lost before a reply "
+                "arrived. Safe to retry after checking connectivity. Nothing was stored."
+            ),
+            trace=(
+                "ProviderVerifier probed the provider's /v1/models and httpx raised an HTTPError."
+            ),
+            hint="Check connectivity and retry.",
+            cause=cause,
+        )
+
+
+class ProviderApiProtocolError(CliError):
+    """The provider returned an undecodable success response."""
+
+    code = CliErrorCode.API_PROTOCOL_ERROR
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+
+    def __init__(self, provider: str, cause: Exception | None = None) -> None:
+        super().__init__(
+            f"The {provider} provider returned an unsupported response.",
+            description=(
+                "The reply succeeded at HTTP level but was not JSON of the expected shape: "
+                "wrong body, empty, or failed validation. The body is not quoted. Retry may "
+                "produce the same result if the provider changed shape."
+            ),
+            trace=(
+                "ProviderVerifier received a 2xx and handed the body to its JSON decoder "
+                "and shape validator."
+            ),
+            hint="Retry once; if current, report with --debug.",
+            cause=cause,
+        )
+
+
+class ProviderRateLimited(CliError):
+    """The provider rate-limited the verification probe."""
+
+    code = CliErrorCode.API_UNAVAILABLE
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+    retryable = True
+
+    def __init__(self, provider: str, retry_after: int | None = None) -> None:
+        wait = (
+            f"Wait {retry_after} seconds before retrying."
+            if retry_after is not None
+            else "Wait before retrying."
+        )
+        super().__init__(
+            f"The {provider} provider rate-limited the request.",
+            description=(
+                "The provider answered 429 for the /v1/models probe. Nothing was stored. "
+                "Waiting before retrying is required."
+            ),
+            trace=(
+                "ProviderVerifier probed the provider and classified the 429 status as "
+                "rate-limited."
+            ),
+            hint=wait,
+        )
+
+
+class ProviderRequestRejected(CliError):
+    """The provider rejected the request as invalid."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(self, provider: str) -> None:
+        super().__init__(
+            f"The {provider} provider rejected the request.",
+            description=(
+                "The provider answered 400/404/422 for the probe, meaning the request was "
+                "malformed. Nothing was stored. The provider body is not echoed."
+            ),
+            trace=(
+                "ProviderVerifier probed the provider and mapped the non-success status "
+                "to a request error."
+            ),
+            hint="Check the key and retry with a fresh token.",
+        )
+
+
+class InvalidProviderApiKeyInput(CliError):
+    """The token for a provider was empty or too large."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(self, provider: str) -> None:
+        super().__init__(
+            f"The supplied {provider} API key is empty or too large.",
+            description=(
+                "The value after trimming was blank or longer than 4096 characters. Nothing "
+                "was verified or stored."
+            ),
+            trace=(
+                "ProviderCredentialInput.read bounds-checked the trimmed value before "
+                "constructing ProviderCredentials."
+            ),
+            hint="Paste the key from the provider dashboard, or pipe with --with-token.",
+        )
+
+
+class ProviderKeyNotLiveFormat(CliError):
+    """The token does not match the expected provider prefix."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(self, provider: str) -> None:
+        super().__init__(
+            f"The value is not a {provider} API key.",
+            description=(
+                "The value does not begin with the expected prefix for this provider. "
+                "OpenAI keys must start with 'sk-' and Claude keys with 'sk-ant-'. "
+                "Nothing was verified or stored."
+            ),
+            trace=(
+                "ProviderCredentialInput.read asked ProviderCredentials.is_live_format "
+                "about the prefix."
+            ),
+            hint="Copy the correct provider key and retry.",
+        )
+
+
+class NoninteractiveProviderLoginRequiresToken(CliError):
+    """Provider login had no terminal and no stdin marker."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(self, provider: str) -> None:
+        super().__init__(
+            "Provider login requires explicit token input in noninteractive mode.",
+            description=(
+                "The hidden prompt needs an interactive terminal, and this invocation has "
+                "none or passed --no-input. Stdin is read only with --with-token."
+            ),
+            trace=("ProviderCredentialInput.read checked --no-input and terminal capabilities."),
+            hint=f"Pipe the token to 'vidbyte-cli provider login {provider} --with-token'.",
+        )
+
+
+class InvalidProviderEnvironmentKey(CliError):
+    """A provider env var is set but unusable."""
+
+    code = CliErrorCode.AUTH_REQUIRED
+    exit_status = ExitCode.AUTHENTICATION
+
+    def __init__(self, provider: str, var_name: str) -> None:
+        super().__init__(
+            f"{var_name} for '{provider}' is empty or invalid.",
+            description=(
+                "The provider environment variable is set to an empty, whitespace-only, "
+                "oversized, or wrong-prefix value. Because it is set it outranks stored "
+                "credentials, so falling through would authenticate as someone the caller "
+                "did not ask for."
+            ),
+            trace=(
+                "ProviderResolver.resolve read the provider env var and bounds/prefix "
+                "checked it before any store."
+            ),
+            hint=f"Set a valid key in {var_name} or unset it to use stored credentials.",
+        )
+
+
+class ProviderAuthenticationRequired(CliError):
+    """A provider command needs a stored key but none exists."""
+
+    code = CliErrorCode.AUTH_REQUIRED
+    exit_status = ExitCode.AUTHENTICATION
+
+    def __init__(self, provider: str) -> None:
+        super().__init__(
+            f"Authentication for provider '{provider}' is required.",
+            description=(
+                "The command needs a provider API key and the store held none for this "
+                "machine/profile. No provider probe was made."
+            ),
+            trace=(
+                "ProviderWhoamiCommand resolved via ProviderResolver, which found no key "
+                "in environment, keyring, or file."
+            ),
+            hint=f"Run 'vidbyte-cli provider login {provider}' first.",
+        )
+
+
+class FileFallbackNotApprovedForProvider(CliError):
+    """Provider login could not ask for fallback consent."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(self, typed_name: str = "provider") -> None:
+        _ = typed_name
+        super().__init__(
+            "No OS keyring is available and provider file storage was not approved.",
+            description=(
+                "Storing the provider key would require the restricted-file fallback, which "
+                "needs explicit consent. This invocation is noninteractive so the prompt "
+                "cannot be shown. Nothing was stored."
+            ),
+            trace=(
+                "ProviderLoginCommand._fallback_consent found no available keyring, no "
+                "--allow-file-fallback, and no interactive terminal."
+            ),
+            hint="Retry with --allow-file-fallback.",
+        )
+
+
+class ResearchWatchTimedOut(CliError):
+    """The local wait expired while the run was still in progress."""
+
+    code = CliErrorCode.OPERATION_FAILED
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+    retryable = True
+
+    def __init__(self, run_id: str) -> None:
+        super().__init__(
+            "The local wait expired before the research run finished.",
+            description=(
+                "Only the local wait ended. The run is still executing on the backend and will "
+                "settle on its own, so nothing was cancelled and no credits were refunded or "
+                "re-spent. Research runs routinely outlast a short --timeout. Read the run "
+                "again later, or watch it again with a longer timeout."
+            ),
+            trace=(
+                "ResearchWatchCommand polled the run status until the elapsed time reached the "
+                "--timeout bound without observing a terminal status."
+            ),
+            hint=f"Run 'vidbyte-cli research status {run_id}' to check on it.",
+        )
+
+
+class StagesHostFailed(CliError):
+    """A stages turn did not complete with a usable Codex reply."""
+
+    code = CliErrorCode.OPERATION_FAILED
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+
+    def __init__(self) -> None:
+        # Host diagnostics can quote task text, so this message stays static.
+        super().__init__(
+            "Codex did not complete the stages turn.",
+            description=(
+                "Codex failed, timed out, or returned an incomplete reply for one stage. "
+                "Execution stopped immediately and later stages never started. The admission "
+                "may already have been charged and completed local work remains in the "
+                "working directory."
+            ),
+            trace="StagesCodexSession checked the SDK turn status and reply identity.",
+            hint="Inspect local Codex configuration before retrying the stages run.",
+        )
+
+
+class StagesSettingsInvalid(CliError):
+    """The supplied stage options did not validate against the stages contract."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(self) -> None:
+        # Reports only the contract, never the submitted stage text.
+        super().__init__(
+            "The run must describe 1 to 25 valid stages.",
+            description=(
+                "No stage was given, more than 25 were given, or a stage carried a blank "
+                "name, prompt, or system prompt. It was rejected before credentials, "
+                "payment, or host execution, so no credits were spent. Give each stage at "
+                "least a --stage-prompt and a --stage-system-prompt and retry."
+            ),
+            trace="StagesOptions validated the stage options before any launch plan was built.",
+            hint="Run 'vidbyte-cli runtime stages describe' for every accepted stage option.",
+        )
+
+
+class StagesOptionCountMismatch(CliError):
+    """Per-stage options were repeated a different number of times than the stages."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(self) -> None:
+        # Names the alignment contract without quoting any submitted stage text.
+        super().__init__(
+            "Every repeated --stage-* option must be given once per stage, or not at all.",
+            description=(
+                "Stages are assembled by position: the first --stage-prompt, the first "
+                "--stage-system-prompt, and the first occurrence of every other --stage-* "
+                "option describe stage 1, the second occurrences describe stage 2, and so "
+                "on. One option repeated a different number of times than --stage-prompt "
+                "leaves the run ambiguous, so it is rejected before payment rather than "
+                "guessed at. An option omitted entirely is not a mismatch: every stage then "
+                "takes that setting's default."
+            ),
+            trace="StagesOptions compared each repeated option list against the prompt count.",
+            hint="Repeat each --stage-* option exactly as many times as --stage-prompt.",
+        )
+
+
+class EnsembleInputsInvalid(CliError):
+    """The supplied ensemble options failed their validated input contract."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(self, cause: Exception) -> None:
+        # Reports the contract, never the submitted values: a task can be sensitive.
+        super().__init__(
+            "The ensemble options are outside their accepted bounds.",
+            description=(
+                "One or more options failed validation before anything else ran. The task must "
+                "hold 1 to 20,000 characters and --roles must be 3 to 100. Nothing was "
+                "submitted, no admission was requested, and no agent started, so correcting "
+                "the option and retrying is safe."
+            ),
+            trace=(
+                "SameHostEnsembleCommand built EnsembleInputs from the parsed options before "
+                "planning a launch."
+            ),
+            hint="Check --roles (3-100), then retry.",
+            cause=cause,
+        )
+
+
+class EnsembleHostUnsupported(CliError):
+    """The resolved host is not the one host this primitive can run on."""
+
+    code = CliErrorCode.CONFIG_INVALID
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+
+    def __init__(self, host: str) -> None:
+        # Auto mode can still resolve to a host this primitive never offers explicitly.
+        super().__init__(
+            f"'{host}' is not a supported host for same-host-ensemble.",
+            description=(
+                "This primitive runs only on Codex, the sole native host with verified thread "
+                "forking and per-fork sandbox control, which is what keeps proposal roles from "
+                "writing to the workspace. No admission was requested and no process started."
+            ),
+            trace=(
+                "SameHostEnsembleCommand checked the resolved RuntimeLaunchPlan's host before "
+                "calling the executor."
+            ),
+            hint="Install Codex, then run 'vidbyte-cli runtime doctor' to confirm discovery.",
+        )
+
+
+class EnsembleSdkUnavailable(CliError):
+    """The Vidbyte SDK is missing, or predates its Codex integration."""
+
+    code = CliErrorCode.CONFIG_INVALID
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+
+    def __init__(self, cause: Exception) -> None:
+        # Raised before admission, so an unmet dependency never costs the caller anything.
+        super().__init__(
+            "The ensemble requires the Vidbyte SDK's Codex integration.",
+            description=(
+                "The Codex agent this primitive drives could not be imported. Either the SDK is "
+                "not installed, or the installed release predates the Codex integration and so "
+                "imports without the required symbols. This check runs before paid admission, "
+                "so nothing was charged. Install the extra and retry."
+            ),
+            trace="SameHostEnsembleCommand loaded the SDK before requesting admission.",
+            hint="Install with: pip install 'vidbyte-cli[codex]'",
+            cause=cause,
+        )
+
+
+class EnsembleRolePlanInvalid(CliError):
+    """The planner turn did not return a usable roster of generated roles."""
+
+    code = CliErrorCode.API_PROTOCOL_ERROR
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+
+    def __init__(self, expected: int) -> None:
+        # The roster is generated, so a bad plan is a host failure rather than caller error.
+        super().__init__(
+            f"The planner did not return {expected} usable roles.",
+            description=(
+                "The first ensemble stage returned no structured role plan, returned a "
+                "different number of roles than requested, or reused a role name. Every later "
+                "stage forks from that plan and every candidate is labeled by its role, so the "
+                "run stopped here rather than fanning out to an ambiguous roster. Admission "
+                "was already granted for this attempt."
+            ),
+            trace=(
+                "EnsembleService._plan_roles read the planner reply's structured output before "
+                "forking any proposal role."
+            ),
+            hint="Retry, or lower --roles if the host struggles to differentiate that many.",
+        )
+
+
+class EnsembleProposalUnusable(CliError):
+    """One role returned no structured proposal, so that branch produced nothing."""
+
+    code = CliErrorCode.API_PROTOCOL_ERROR
+    exit_status = ExitCode.PARTIAL_OUTCOME
+
+    def __init__(self, role: str) -> None:
+        # Recorded as a per-role failure; it aborts the run only if every role fails.
+        super().__init__(
+            f"Role '{role}' returned no usable proposals.",
+            description=(
+                "This role's fork completed without producing structured output matching the "
+                "proposal contract, which requires 5 to 10 approaches with pros and cons on "
+                "each. The role is recorded as failed and the run continues with whichever "
+                "roles did succeed, because a partial ensemble still beats a single agent. "
+                "Only an empty slate stops the run."
+            ),
+            trace=(
+                "EnsembleService._propose validated one fork's structured reply before the "
+                "fan-in stage collected it."
+            ),
+            hint="Inspect the failures list in the result document for the affected roles.",
+        )
+
+
+class EnsembleAllRolesFailed(CliError):
+    """Every proposal role failed, so there is nothing to hand the implementer."""
+
+    code = CliErrorCode.OPERATION_FAILED
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+
+    def __init__(self, failed: int) -> None:
+        # Running the implementer on an empty proposal set would just be a solo agent.
+        super().__init__(
+            f"All {failed} ensemble roles failed.",
+            description=(
+                "No role produced a usable slate, through timeout, host failure, or invalid "
+                "output. The selection and implementer stages were not started, because "
+                "running them with no candidates would be an expensive way to run one ordinary "
+                "agent. No file in the workspace was modified; admission for this attempt was "
+                "already granted."
+            ),
+            trace=(
+                "EnsembleService._orchestrate partitioned the gathered role outcomes and found "
+                "no surviving proposal."
+            ),
+            hint="Retry, or check 'vidbyte-cli runtime doctor' for host health.",
+        )
+
+
+class EnsembleHostFailed(CliError):
+    """The native host failed during a stage whose failure ends the run."""
+
+    code = CliErrorCode.OPERATION_FAILED
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+
+    def __init__(self, stage: str, cause: Exception) -> None:
+        # The provider message is withheld: it can carry workspace paths and prompt text.
+        super().__init__(
+            f"The native host failed during the ensemble {stage} stage.",
+            description=(
+                "Codex raised while running this stage. The provider's own message is withheld "
+                "because it can quote workspace paths and prompt text. Planner and selector "
+                "failures end the run, unlike a single role's failure, because every later "
+                "stage depends on them. No partial work was applied by this stage."
+            ),
+            trace=(
+                "EnsembleService drove one Codex turn or fork through the Vidbyte SDK's Codex "
+                "agent and the SDK raised."
+            ),
+            hint="Run 'vidbyte-cli runtime doctor', then retry.",
+            cause=cause,
+        )
+
+
+class EnsembleSelectionInvalid(CliError):
+    """A narrowing round did not return the survivors it was told to return."""
+
+    code = CliErrorCode.API_PROTOCOL_ERROR
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+
+    def __init__(self, expected: int) -> None:
+        # The ladder is computed locally, so a round that ignores its target is unrecoverable.
+        super().__init__(
+            f"The selector did not keep exactly {expected} candidate(s).",
+            description=(
+                "One narrowing round returned no structured output, kept a number of "
+                "candidates other than the one it was given, repeated a candidate, or named an "
+                "identifier that was not on the slate for that round. Each round's survivors "
+                "decide the next round's slate, so the run stopped rather than continuing from "
+                "an unverifiable set. No workspace file was modified; admission for this "
+                "attempt was already granted."
+            ),
+            trace=(
+                "EnsembleService._round validated one selection round's structured reply "
+                "against the candidate identifiers that round was offered."
+            ),
+            hint="Retry, or lower --roles so the first round weighs fewer candidates.",
+        )
+
+
+class EnsembleImplementerFailed(CliError):
+    """The write-enabled implementer stage failed after an approach was selected."""
+
+    code = CliErrorCode.OPERATION_FAILED
+    exit_status = ExitCode.PARTIAL_OUTCOME
+
+    def __init__(self, cause: Exception) -> None:
+        # The one stage that may write, so a failure here can leave partial edits behind.
+        super().__init__(
+            "The ensemble implementer stage failed.",
+            description=(
+                "An approach was proposed and selected successfully, but the write-enabled "
+                "implementer fork failed. This is the only stage permitted to modify the "
+                "workspace, so it may have applied some changes before failing. Review the "
+                "working tree before retrying, because a retry starts the task from the "
+                "beginning."
+            ),
+            trace=(
+                "EnsembleService._implement forked the root thread with write access and ran "
+                "the implementation turn."
+            ),
+            hint="Check 'git status' for partial edits before retrying.",
+            cause=cause,
+        )
+
+
+class RuntimePaymentFailed(CliError):
+    """Explicit x402 admission could not be safely authorized or completed."""
+
+    code = CliErrorCode.OPERATION_FAILED
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+
+    def __init__(self, reason: str) -> None:
+        # Exposes only a fixed reason category, never payer credentials or response bodies.
+        super().__init__(
+            "Runtime x402 payment could not be completed.",
+            description=(
+                "Set VIDBYTE_X402_PRIVATE_KEY and the supported VIDBYTE_X402_NETWORK for "
+                "explicit x402 payment. No local agent was launched. If payment was already "
+                "attempted, recover with the same idempotency key; do not authorize a new "
+                f"purchase to resolve an uncertain outcome. Reason: {reason}."
+            ),
+            trace="Runtime payment validation failed before the database-verified launch gate.",
+        )
+
+
+class SuggestionInputInvalid(CliError):
+    """The suggestion request was missing, mixed, or malformed."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(self) -> None:
+        # Never echoes goal text or file bodies, which can carry private task data.
+        super().__init__(
+            "Supply a nonempty goal and valid suggestion settings.",
+            description=(
+                "A suggestion run receives its goal and settings from the declared command "
+                "flags, and those values must form one strict request. An empty goal, an "
+                "out-of-range setting, or a malformed value fails here. Nothing was read "
+                "from providers and no model was called."
+            ),
+            trace="SuggestRunCommand validated the request before building context.",
+            hint="Run with --goal 'outcome' and keep --count between 2 and 15.",
+        )
+
+
+class SuggestionCategoryUnknown(CliError):
+    """An unknown suggestion category was requested."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(self, detail: str) -> None:
+        # Carries only the unknown ids, never goal or context content.
+        super().__init__(
+            f"Unknown suggestion category: {detail}.",
+            description=(
+                "Category ids come from a fixed registry shared by validation, prompts, and "
+                "schemas. An unknown id fails before files are read or models run, so a typo "
+                "cannot silently widen generation. List valid ids without credentials or "
+                "network access."
+            ),
+            trace="SuggestRunCommand checked categories against the owned registry.",
+            hint="Run 'vidbyte-cli agents suggest categories' to list valid ids.",
+        )
+
+
+class SuggestionContextUnreadable(CliError):
+    """An explicit context file could not be read or parsed."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(self, detail: str) -> None:
+        # Omits paths and bodies, which may name private files or task data.
+        super().__init__(
+            f"Could not read suggestion context: {detail}.",
+            description=(
+                "Only explicitly supplied files are read, and each must be UTF-8 text, "
+                "Markdown, or documented JSON with a supported schema version. Missing "
+                "files, directories, malformed JSON, and unsupported types fail here. No "
+                "model was called and no provider configuration was required."
+            ),
+            trace="SuggestionContextBuilder read one explicit context path.",
+            hint="Check the path suffix, encoding, and JSON schema version.",
+        )
+
+
+class SuggestionLimitExceeded(CliError):
+    """A generation limit was unusable for this run."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(self) -> None:
+        # Counts and bounds are CLI-validated, so this is a narrow guard.
+        super().__init__(
+            "A suggestion limit is outside its supported range.",
+            description=(
+                "Counts, rounds, token bounds, and timeouts are stopping thresholds for "
+                "the whole workflow including revisions. Out-of-range values fail before "
+                "any model call so callers get usage errors rather than partial runs. No "
+                "provider work started."
+            ),
+            trace="SuggestRunCommand validated generation controls before the service.",
+            hint="Use --count 2-15, --rounds 1-3, and positive token/timeout values.",
+        )
+
+
+class SuggestionProviderFailed(CliError):
+    """The model provider failed during generation or critique."""
+
+    code = CliErrorCode.OPERATION_FAILED
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+
+    def __init__(self, cause: Exception) -> None:
+        # Withholds provider text, which can quote prompts and workspace paths.
+        super().__init__(
+            "The suggestion provider did not complete the run.",
+            description=(
+                "The provider raised, timed out, or returned output that did not validate "
+                "during generation or critique. This is reported as a provider failure, never "
+                "as no useful suggestions, so callers do not misread an outage as a verdict. "
+                "Partial reviewed batches are preserved where the service kept them."
+            ),
+            trace="SuggestionService drove one generator or critic turn via the SDK.",
+            hint=(
+                "Retry the provider run, or use --dry-run to validate the request without a model."
+            ),
+            cause=cause,
+        )
+
+
+class SuggestionSdkUnavailable(CliError):
+    """The installed SDK predates the integration the suggestion agent needs."""
+
+    code = CliErrorCode.OPERATION_FAILED
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+
+    def __init__(self, cause: Exception) -> None:
+        # Static text only; the missing symbol path is an install fact, not a secret.
+        super().__init__(
+            "The installed vidbyte-sdk does not expose the suggestion integration.",
+            description=(
+                "Suggestion SDK symbols resolve lazily so help and category listing work "
+                "without them. A run that explicitly requires provider execution fails here "
+                "when the pinned SDK revision is absent or predates the integration. Category "
+                "inspection and request validation remain available without provider flags."
+            ),
+            trace="SuggestionSdk resolved Codex agent symbols at call time.",
+            hint="Install the SDK revision pinned in pyproject.toml.",
+            cause=cause,
+        )
+
+
+class SuggestionProjectInvalid(CliError):
+    """A project key, title, or description did not satisfy the local project contract."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(self, detail: str) -> None:
+        # Reports validation guidance without echoing descriptions or feedback bodies.
+        super().__init__(
+            f"Invalid suggestion project: {detail}.",
+            description=(
+                "A project key must be 1-64 lowercase letters, numbers, hyphens, or "
+                "underscores beginning with a letter or number, and a new project also needs a "
+                "nonempty title of at most 200 characters and description of at most 4000. The "
+                "request was rejected before any project file was read or written. Existing "
+                "projects and their feedback were not changed."
+            ),
+            trace="SuggestionProject validated the key and fields in its input dataclass.",
+            hint="Use --key with lowercase letters, numbers, hyphens, or underscores.",
+        )
+
+
+class SuggestionProjectExists(CliError):
+    """A project create request used a key already present in local state."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(self, key: str) -> None:
+        # Keeps duplicate creation separate from malformed project input.
+        super().__init__(
+            f"Suggestion project already exists: {key}.",
+            description=(
+                "The project key is already registered in the local suggestion catalog. "
+                "No catalog or memory file was replaced, so the existing project remains "
+                "unchanged. Choose another key or use the existing project key for feedback "
+                "and suggestion runs."
+            ),
+            trace="SuggestionProject found a duplicate key before its first write.",
+            hint="Run 'vidbyte-cli agents suggest project list' to inspect existing keys.",
+        )
+
+
+class SuggestionProjectNotFound(CliError):
+    """A project-dependent command addressed a key absent from local state."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(self, key: str) -> None:
+        # Names the missing selector so an agent can repair the invocation directly.
+        super().__init__(
+            f"Suggestion project was not found: {key}.",
+            description=(
+                "The requested project key is not present in the local suggestion catalog. "
+                "The command did not create a project implicitly and did not modify any "
+                "memory file. Create the project first or choose a key from the project list."
+            ),
+            trace="SuggestionProject looked up an exact project key in projects.json.",
+            hint="Run 'vidbyte-cli agents suggest project list' or create the project first.",
+        )
+
+
+class SuggestionProjectStateUnreadable(CliError):
+    """The local project catalog or linked memory file is malformed or inaccessible."""
+
+    code = CliErrorCode.OPERATION_FAILED
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+
+    def __init__(self, detail: str, cause: Exception | None = None) -> None:
+        # Withholds file contents and absolute paths from normal agent-facing output.
+        super().__init__(
+            "Suggestion project state could not be read.",
+            description=(
+                "An existing project catalog or memory file was missing, malformed, "
+                "unsupported, or inaccessible. No model call was made and no valid project "
+                "memory was silently replaced. Repair or remove only the invalid suggestion "
+                "state, then retry the command."
+            ),
+            trace=f"SuggestionProject rejected local JSON state: {detail}.",
+            hint="Inspect projects.json and the linked project memory file for schema version 1.",
+            cause=cause,
+        )
+
+
+class SuggestionProjectWriteFailed(CliError):
+    """The operating system refused to persist a project or feedback document."""
+
+    code = CliErrorCode.OPERATION_FAILED
+    exit_status = ExitCode.OPERATIONAL_FAILURE
+
+    def __init__(self, cause: Exception) -> None:
+        # States that were already valid remain on disk because writes are atomic.
+        super().__init__(
+            "Suggestion project state could not be written.",
+            description=(
+                "The local filesystem refused an atomic project or feedback replacement. "
+                "The prior valid document was preserved, and the command did not report a "
+                "successful mutation. Check the data directory permissions and available "
+                "space before retrying."
+            ),
+            trace="SuggestionProject failed while replacing a local JSON document.",
+            hint="Check the Vidbyte data directory and retry the command.",
+            cause=cause,
+        )
+
+
+class SuggestionFeedbackInvalid(CliError):
+    """An accepted or rejected feedback request was incomplete or malformed."""
+
+    code = CliErrorCode.INVALID_ARGUMENT
+    exit_status = ExitCode.USAGE
+
+    def __init__(self, detail: str) -> None:
+        # Keeps feedback validation separate from project lookup and file errors.
+        super().__init__(
+            f"Invalid suggestion feedback: {detail}.",
+            description=(
+                "Feedback requires an existing project and nonempty suggestion text of at most "
+                "8192 characters, with an optional reason of the same bound. The request was "
+                "rejected before the memory file changed. The CLI never infers acceptance or "
+                "rejection from an ambiguous user response."
+            ),
+            trace="SuggestionFeedbackInput validated explicit feedback before persistence.",
+            hint=(
+                "Pass --project and --suggestion, and call the command only for explicit feedback."
+            ),
+        )