Enum CliError 

pub enum CliError {
    NotAVolume,
    VolumeAlreadyExists {
        path: PathBuf,
    },
    ValidationFailed {
        issues: Vec<String>,
    },
    Distro(Error),
    Manifest(Error),
    Github(Error),
    Tarball(Error),
    TarballLayoutMismatch {
        expected: String,
        found: Vec<String>,
    },
    Python(Error),
    UnsafeTarget {
        path: PathBuf,
    },
    SymlinkPrivilegeRequired,
    UlidLockTimeout {
        path: PathBuf,
    },
    Ulid(Error),
    Worktree(Error),
    EventLog(Error),
    ClaudeProc(Error),
    Dispatch(DispatchError),
    Io(String),
    RunNotFound(String),
    PipeAborted {
        run_id: String,
        reason: String,
    },
}

Error variant categories map to process exit codes at main.rs: logical errors (cross-cutting variants and module-wrapper variants) exit with code 1; clap argument-parse errors exit with code 2 via clap’s own machinery. Successful runs exit with code 0.

The variants below are reserved for the command handlers that land in Units 8a, 9, and 10. The earlier units only wire up the dispatcher, stub handlers, and leaf modules, so none of the variants are constructed yet — the #[allow(dead_code)] is scoped to the enum and will be removed automatically as each variant picks up a first call site.

Variants

NotAVolume

Walk-up from the current directory did not find a .omne/ root. Produced by upgrade and validate when invoked outside a volume.

VolumeAlreadyExists

Produced by init when the current directory already contains a .omne/ directory. The precheck deliberately does not walk up, per R13: init creates in the current directory only.

Fields

path: PathBuf

ValidationFailed

Produced by validate after collecting one or more issues. The issue strings are carried in the variant so callers and tests can introspect them structurally; main.rs prints the header and each issue line.

Fields

issues: Vec<String>

Distro(Error)

Wraps distro::Error (e.g. UnsupportedSpec for file:// or non-github.com hosts). Produced by init at argument parse time.

Manifest(Error)

Wraps manifest::Error (missing frontmatter, missing required field, YAML parse failure). Produced by upgrade and validate when reading .omne/omne.md.

Github(Error)

Wraps github::Error (rate limit, auth failure, no release found, no tarball asset, sanitized HTTP error). Produced by init and upgrade when fetching releases.

Tarball(Error)

Wraps tarball::Error (path traversal, unsupported entry type, pre-planted symlink, I/O). Produced during tarball extraction in init and upgrade.

TarballLayoutMismatch

The extracted tarball did not contain the expected top-level directory (e.g. core/ for kernel, dist/ for distro). Indicates the upstream release workflow changed its tarball layout.

Fields

expected: String

found: Vec<String>

Python(Error)

Wraps python::Error (gate runner failure, timeout, interpreter invocation failure). Produced by validate when running the gate runner script.

UnsafeTarget

The target directory for upgrade contains or is reached via a symlink. Refusing to remove_dir_all to prevent symlink traversal.

Fields

path: PathBuf

SymlinkPrivilegeRequired

Windows-only: creating a directory symlink failed with ERROR_PRIVILEGE_NOT_HELD (1314). Tells the user the two ways to unlock symlink creation so they can re-run.

UlidLockTimeout

Advisory lock on the ULID allocator file was not released within the acquire budget (default 5s). Produced by run when composing the per-run identifier via crate::ulid::allocate.

Fields

path: PathBuf

Ulid(Error)

Wraps ulid::Error for ULID allocator failures that are not lock timeouts (I/O errors on the lock file, malformed persisted state). Separate variant from UlidLockTimeout so callers can discriminate lock contention from data corruption.

Worktree(Error)

Wraps worktree::Error for git worktree add / remove / list failures surfaced by the runner preflight, executor teardown, and status enumeration.

EventLog(Error)

Wraps event_log::Error for per-run events.jsonl open / append / read / enumerate failures, including the advisory lock timeout surfaced by EventLog::append.

ClaudeProc(Error)

Wraps claude_proc::Error for claude -p subprocess client failures (HostMissing, Spawn, Timeout, ExitedNonZero, stream I/O, capture-file I/O). Surfaced by Unit 11’s executor when a prompt node’s subprocess misbehaves.

Dispatch(DispatchError)

Wraps executor::DispatchError for infrastructure failures surfaced while dispatching a single node (event-log I/O, spawn / wait errors, malformed pipe data slipping past the validator). Distinct from NodeOutcome::Failed, which is a recorded node failure — a Dispatch error means the executor couldn’t even decide the outcome.

Io(String)

Wraps std::io::Error for filesystem and cwd operations.

RunNotFound(String)

omne status <run_id> for a run that does not exist.

PipeAborted

A run completed with at least one Failed or Blocked node. The event log has already recorded pipe.aborted; this error is the CLI-surface representation so main.rs exits non-zero without re-deriving the state.

Fields

run_id: String

reason: String

Implementations

impl CliError

pub fn exit_code(&self) -> i32

Exit code mapping for the process. All logical errors map to 1; clap parser failures exit with 2 via clap itself. Matches the Python CLI’s exit code contract.

Trait Implementations

impl Debug for CliError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for CliError

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for CliError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<DispatchError> for CliError

fn from(source: DispatchError) -> Self

Converts to this type from the input type.

impl From<Error> for CliError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<Error> for CliError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<Error> for CliError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<Error> for CliError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<Error> for CliError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<Error> for CliError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<Error> for CliError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<Error> for CliError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<Error> for CliError

fn from(err: Error) -> Self

Converts to this type from the input type.

impl From<Error> for CliError

fn from(err: Error) -> Self

Converts to this type from the input type.